Foundation Kit

Status: early development. The packages work, but nothing is released yet and the API will change until there is. Consumers are being migrated to bundle now. See Packages for what works today.

The problem it solves

Applications tend to grow a separate loader for each type of content, each with its own file layout, parser, naming rule and error format. cclab-platform, for example, reaches 55 files through seven unrelated mechanisms.

Foundation Kit replaces that with one pipeline. You declare a kind of content and how to read it, and the kit handles path safety, identity, digests, linking and error reporting:

// Declare a kind next to the type it produces.
var Profile = kind.New[ProfileSpec]("example.profile", 1)

// Load bundles from disk and built-in definitions from Go code into one catalog.
catalog, err := bundle.Load(ctx, bundle.Options{
	Sources:   []bundle.Source{bundle.Dir("res/profiles")},
	Compilers: []bundle.AnyCompiler{bundle.Compile(Profile, compile.JSON[ProfileSpec]())},
	Providers: []kind.Provider{{
		ID:       "example.builtins",
		Version:  "1.0.0",
		Builtins: []kind.AnyBuiltin{kind.Builtin(Profile, "default", ProfileSpec{Retries: 3})},
	}},
})
if err != nil {
	return err // lists every problem at once, not just the first
}

// Read definitions back with their Go type, and no casting.
for _, def := range bundle.All(catalog, Profile) {
	fmt.Println(def.Ref, def.Value.Retries)
}

A bundle is a directory with a bundle.yaml at its root. The manifest is always required, and is never generated from a folder layout:

profiles/
├── bundle.yaml
└── fast.json

apiVersion: craggy.io/bundle/v1

metadata:
  id: example.profiles
  version: 0.1.0

contributions:
  - id: fast
    kind: example.profile@1
    path: fast.json

Layers

The kit is organised in layers, and imports only ever point down. This is what lets it keep growing: a library can use a low layer without inheriting everything above it.

Nothing in the kit knows about any product. If a package needs a word like "lab" or "APK", it belongs in the library or application that owns that concept.

Packages

We also expect to add packages for lifecycle management, logging and an HTTP server. None of them exist yet, and each will be added once real applications need it.

Using it

The kit requires Go 1.25 or later, and its module path is github.com/craggy-io/foundation-kit. There's no tagged release yet, and the API will change until there is.

To develop the kit alongside an application, use an uncommitted go.work file rather than a replace directive in go.mod.

Contributing

go build ./... && go vet ./... && go test ./...
(cd adapters/sqlite && go vet ./... && go test ./...)

Before adding a package, check the rules for what belongs in the kit. They apply to people as well as coding agents.

Documentation