README
¶
Spice Toolchain
This repository contains Spice's compile-time developer toolchain: the
compiler, generator, command-line interface, language server, scaffold support,
and official annotation protocol executable. Runtime APIs, public annotation
descriptors, and the annotation SDK live in
github.com/spice-framework/spice.
The boundary is intentionally explicit:
github.com/spice-framework/spiceowns public application-facing Go APIs.github.com/spice-framework/toolchainowns compiler and executable code.- applications authorize both
cmd/spiceandcmd/spice-annotation-corewith ordinary Gotooldirectives; - the official annotation process serves descriptors from the core module, but third-party descriptors and tools remain in the same resolved Go module;
- generated application code imports public core packages and never imports the compiler or CLI.
Install in an application
With Go 1.26.5:
go get -tool github.com/spice-framework/toolchain/cmd/spice@<exact-version>
go get -tool github.com/spice-framework/toolchain/cmd/spice-annotation-core@<exact-version>
Then run the complete package-oriented workflow:
go tool github.com/spice-framework/toolchain/cmd/spice verify ./...
go tool github.com/spice-framework/toolchain/cmd/spice generate ./...
go tool github.com/spice-framework/toolchain/cmd/spice build ./...
spice new writes both tool declarations and independently pins the public core
and toolchain module versions. It never downloads modules implicitly.
Develop
The repository requires exactly Go 1.26.5. Use:
make fast
make check
make benchmark
make verify
The verifier is implemented in Go, so its behavior is the same from PowerShell, Linux, and macOS. The definitive gate checks module and vendor reproducibility, builds every published tool, tests the compiler/CLI/LSP boundary, rejects stale monorepository imports, enforces pinned formatting, lint, nil-safety, security, race, fuzz, and 85% coverage gates, and generates a third-party SDK fixture twice from zero before compiling and executing it offline.
The definitive gate also enforces the versioned latency, allocation, and memory
ceilings in benchmarks/budgets.json. Five samples
per critical path are reduced to a median to limit scheduler noise. Run
make benchmark for that focused contract without waiting for the full gate;
the budgets remain mandatory in make verify and therefore in every release.
Before the offline fixture tests, the gate explicitly acquires and verifies the fixture's declared Go modules. Product analysis, generation, LSP operation, and the subsequent fixture workflow all run with network lookup disabled.
The third-party fixture under testdata/ is handwritten. Its generated output
is deliberately untracked and recreated by verification.
Release
RELEASING.md defines the release contract. Production builds
require a clean checkout at the exact canonical SemVer tag, the tag's commit epoch,
Go 1.26.5, and an external Ed25519 signing key. Rehearsals are deliberately
unsigned. Every build uses the committed Git snapshot, the vendor graph, a
scrubbed offline Go environment, and emits deterministic platform archives, a
source archive, an exact SPDX SBOM, checksums, and (for production) a detached
checksum signature. The tag workflow independently authenticates the signed
artifacts against the committed trust anchor, compares a clean Windows rebuild
byte-for-byte, and grants repository write authority only after a separate
protected publication approval. That final job creates a private draft,
downloads and reverifies every byte, and only then publishes it. The trust
anchor and protected environments in
RELEASING.md are mandatory before creating a release tag.
Signed source-only starter releases use a separate trust boundary. The
cmd/spice-library-release-verify Go tool authenticates the exact five-file
artifact set with an externally trusted Ed25519 public key, then independently
checks the source archive and SPDX 2.3 document against an exact commit in the
trusted starter checkout. Callers must also provide the expected canonical
HTTPS source URL and Go module path; repository-name coincidence alone is not a
trust decision. It does not import the central development renderer, the
retained starter builder, or this repository's binary-release builder. Starter
workflows authorize an exact verifier version with an ordinary root go.mod
tool directive and run it in vendor-only offline mode.
The separately explicit make release-acceptance proof is network-capable by
design and is not part of make verify. It clones the central development
signer and starter-oidc at repository-pinned commit IDs, creates a clean
temporary checkout with the canonical HTTPS origin and an exact temporary tag,
signs with a newly generated ephemeral Ed25519 key, and passes those artifacts
to this repository's independent verifier with explicit source and module
identity. Its hosted workflow runs on Linux and Windows. All Go builds remain
vendor-only and offline; network access is limited to the two pinned Git
fetches, and the temporary clones, artifacts, and private key are deleted when
the proof finishes.
Extraction provenance
The repository retains the filtered history of the compiler/tooling boundary.
Its public-core bridge is pinned to
github.com/spice-framework/spice@v0.0.0-20260805222830-a2ecd56df246
(commit a2ecd56df246ad3a647b64b0585738a2495ecf5c). The Apache-2.0 license and
pinned quality-tool versions were carried from the extracted source history,
then the module identities and standalone gate were adapted here. No migration
script or machine-specific replacement is part of the published tree.
Extraction status
This initial standalone boundary intentionally runs cmd/spice through the
handwritten CLI, exactly like cmd/spice-bootstrap. The former monorepository's
stale generated self-hosted command was removed rather than published under the
wrong module identity. Production self-hosting remains a follow-up integration
milestone; this repository does not claim it yet. Performance budgets and the
artifact build are guarded and reproducible as documented above.
License
Apache License 2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
spice
command
Command spice is the standalone Spice compiler and developer-tool entrypoint.
|
Command spice is the standalone Spice compiler and developer-tool entrypoint. |
|
spice-annotation-core
command
|
|
|
spice-bootstrap
command
Command spice-bootstrap is the ordinary-Go stage-zero Spice compiler.
|
Command spice-bootstrap is the ordinary-Go stage-zero Spice compiler. |
|
spice-library-release-verify
command
Command spice-library-release-verify independently authenticates a signed Spice library release against an exact commit in a trusted checkout.
|
Command spice-library-release-verify independently authenticates a signed Spice library release against an exact commit in a trusted checkout. |
|
spice-release
command
Command spice-release builds deterministic, signed Spice release artifacts.
|
Command spice-release builds deterministic, signed Spice release artifacts. |
|
spice-release-verify
command
Command spice-release-verify independently authenticates and verifies a complete Spice release artifact directory.
|
Command spice-release-verify independently authenticates and verifies a complete Spice release artifact directory. |
|
Package compiler owns Spice's ordinary-Go analysis and generation pipeline.
|
Package compiler owns Spice's ordinary-Go analysis and generation pipeline. |
|
annotationcatalog
Package annotationcatalog discovers statically declared annotation descriptors from the target application's existing offline Go module graph.
|
Package annotationcatalog discovers statically declared annotation descriptors from the target application's existing offline Go module graph. |
|
annotationhost
Package annotationhost authorizes and hosts Go-native annotation tools.
|
Package annotationhost authorizes and hosts Go-native annotation tools. |
|
annotationimport
Package annotationimport resolves explicit file-scoped annotation imports.
|
Package annotationimport resolves explicit file-scoped annotation imports. |
|
annotationinstall
Package annotationinstall plans and applies hash-guarded Go module changes.
|
Package annotationinstall plans and applies hash-guarded Go module changes. |
|
application
Package application assembles the immutable Spice application model from one resolved, type-aware compiler program.
|
Package application assembles the immutable Spice application model from one resolved, type-aware compiler program. |
|
async
Package async compiles provider-owned asynchronous method annotations into deterministic metadata.
|
Package async compiles provider-owned asynchronous method annotations into deterministic metadata. |
|
autoconfigure
Package autoconfigure discovers and statically decodes Go-native library auto-configuration.
|
Package autoconfigure discovers and statically decodes Go-native library auto-configuration. |
|
bootstrap
Package bootstrap compiles qualified application-platform annotations into deterministic, immutable metadata for the Spice application IR.
|
Package bootstrap compiles qualified application-platform annotations into deterministic, immutable metadata for the Spice application IR. |
|
cache
Package cache compiles explicit cacheable HTTP read boundaries into deterministic metadata.
|
Package cache compiles explicit cacheable HTTP read boundaries into deterministic metadata. |
|
configuration
Package configuration validates reflection-free configuration declarations from the shared typed compiler program.
|
Package configuration validates reflection-free configuration declarations from the shared typed compiler program. |
|
controller
Package controller validates generated net/http controller metadata from the shared typed compiler program.
|
Package controller validates generated net/http controller metadata from the shared typed compiler program. |
|
descriptor
Package descriptor statically decodes annotation SDK descriptor functions from the compiler's single typed Go program.
|
Package descriptor statically decodes annotation SDK descriptor functions from the compiler's single typed Go program. |
|
diagnostic
Package diagnostic defines the shared immutable diagnostic contract consumed by Spice command, development, and editor integrations.
|
Package diagnostic defines the shared immutable diagnostic contract consumed by Spice command, development, and editor integrations. |
|
diagnostic/adapt
Package adapt converts existing compiler-stage diagnostics into the shared Spice diagnostic contract without changing stage-local metadata models.
|
Package adapt converts existing compiler-stage diagnostics into the shared Spice diagnostic contract without changing stage-local metadata models. |
|
event
Package event compiles typed event topic markers and provider-owned listeners into deterministic application metadata.
|
Package event compiles typed event topic markers and provider-owned listeners into deterministic application metadata. |
|
generate
Package generate renders deterministic generated application plans from one validated Spice application model.
|
Package generate renders deterministic generated application plans from one validated Spice application model. |
|
graph
Package graph validates exact-type provider dependencies and builds a deterministic dependency-first provider construction order.
|
Package graph validates exact-type provider dependencies and builds a deterministic dependency-first provider construction order. |
|
lifecycle
Package lifecycle validates explicit lifecycle-hook metadata against the provider catalog.
|
Package lifecycle validates explicit lifecycle-hook metadata against the provider catalog. |
|
load
Package load provides Spice's single type-aware Go package loading boundary.
|
Package load provides Spice's single type-aware Go package loading boundary. |
|
modulith
Package modulith discovers and validates Spice application-module metadata from the shared typed compiler program.
|
Package modulith discovers and validates Spice application-module metadata from the shared typed compiler program. |
|
parser
Package parser parses Spice annotations embedded in valid Go comments.
|
Package parser parses Spice annotations embedded in valid Go comments. |
|
provider
Package provider builds and validates the compile-time provider catalog.
|
Package provider builds and validates the compile-time provider catalog. |
|
resolve
Package resolve associates parsed Spice annotations with declarations in an already loaded, type-checked Go program.
|
Package resolve associates parsed Spice annotations with declarations in an already loaded, type-checked Go program. |
|
scan
Package scan discovers Spice annotations in Go source files.
|
Package scan discovers Spice annotations in Go source files. |
|
schedule
Package schedule compiles provider-owned fixed-delay annotations into deterministic metadata.
|
Package schedule compiles provider-owned fixed-delay annotations into deterministic metadata. |
|
service
Package service exposes Spice's typed compiler pipeline as an isolated, overlay-aware analysis service for commands and editor integrations.
|
Package service exposes Spice's typed compiler pipeline as an isolated, overlay-aware analysis service for commands and editor integrations. |
|
signature
Package signature provides exact loaded-program signature identities shared by compiler feature analyzers.
|
Package signature provides exact loaded-program signature identities shared by compiler feature analyzers. |
|
starter
Package starter adapts explicitly supplied public starter manifests into compiler annotation and application-bootstrap metadata.
|
Package starter adapts explicitly supplied public starter manifests into compiler annotation and application-bootstrap metadata. |
|
targetid
Package targetid defines the stable generated-package identity shared by lexical entrypoint preparation and typed generation.
|
Package targetid defines the stable generated-package identity shared by lexical entrypoint preparation and typed generation. |
|
transaction
Package transaction compiles explicit transactional HTTP boundaries into deterministic metadata.
|
Package transaction compiles explicit transactional HTTP boundaries into deterministic metadata. |
|
validate
Package validate checks scanned annotations against typed definitions.
|
Package validate checks scanned annotations against typed definitions. |
|
internal
|
|
|
annotationcore
Package annotationcore implements the official Go-native annotation tool.
|
Package annotationcore implements the official Go-native annotation tool. |
|
boundarygate
Package boundarygate owns the focused, cross-platform verification contract for the standalone Spice toolchain repository.
|
Package boundarygate owns the focused, cross-platform verification contract for the standalone Spice toolchain repository. |
|
boundarygate/cmd
command
Command boundarygate runs the standalone repository's verification contract.
|
Command boundarygate runs the standalone repository's verification contract. |
|
cli
Package cli implements the Spice command-line interface.
|
Package cli implements the Spice command-line interface. |
|
devloop
Package devloop coordinates deterministic application rebuilds and restarts for development tools.
|
Package devloop coordinates deterministic application rebuilds and restarts for development tools. |
|
genfs
Package genfs safely compares and applies deterministic generation plans.
|
Package genfs safely compares and applies deterministic generation plans. |
|
gitenv
Package gitenv provides a fail-closed environment for read-only release Git operations.
|
Package gitenv provides a fail-closed environment for read-only release Git operations. |
|
identity
Package identity owns the canonical module and executable identities that cross the public Spice core and toolchain boundary.
|
Package identity owns the canonical module and executable identities that cross the public Spice core and toolchain boundary. |
|
libraryreleaseacceptance
Package libraryreleaseacceptance proves the real central library signer against the independent toolchain verifier using immutable external source.
|
Package libraryreleaseacceptance proves the real central library signer against the independent toolchain verifier using immutable external source. |
|
libraryreleaseacceptance/cmd
command
Command libraryreleaseacceptance runs the hosted cross-producer release proof.
|
Command libraryreleaseacceptance runs the hosted cross-producer release proof. |
|
libraryreleaseverify
Package libraryreleaseverify independently authenticates and verifies a signed Spice library release against an exact commit in a trusted checkout.
|
Package libraryreleaseverify independently authenticates and verifies a signed Spice library release against an exact commit in a trusted checkout. |
|
lsp
Package lsp implements Spice's editor-neutral Language Server Protocol transport over standard JSON-RPC streams.
|
Package lsp implements Spice's editor-neutral Language Server Protocol transport over standard JSON-RPC streams. |
|
moduleenv
Package moduleenv derives fail-closed Go module execution settings.
|
Package moduleenv derives fail-closed Go module execution settings. |
|
release
Package release builds deterministic, signed Spice release artifacts.
|
Package release builds deterministic, signed Spice release artifacts. |
|
releaseverify
Package releaseverify independently verifies a complete Spice release.
|
Package releaseverify independently verifies a complete Spice release. |
|
scaffold
Package scaffold creates minimal, valid-Go Spice applications without downloading dependencies or overwriting developer-owned files.
|
Package scaffold creates minimal, valid-Go Spice applications without downloading dependencies or overwriting developer-owned files. |
|
testannotation
Package testannotation adapts raw parser fixtures to typed SDK semantics.
|
Package testannotation adapts raw parser fixtures to typed SDK semantics. |
|
testsupport
Package testsupport owns portable module fixtures shared by toolchain tests.
|
Package testsupport owns portable module fixtures shared by toolchain tests. |