Contributing

Contributing

Repository Layout

PathPurpose
server/cmd/gestaltdServer entrypoint, command handling, and built-in registration.
server/corePublic interfaces for auth, datastore, secrets, providers, and bindings.
server/internalBootstrap, config loading, invocation, server routing, plugin process management, and other server internals.
pluginsExternal plugin packages (declarative and compiled).
sdkPublic SDKs and plugin manifest definitions.
webFrontend that is embedded into the server build.
docsDocumentation site.
server/deployDocker and Helm deployment assets.

Working Principles

When you update docs, keep them aligned with:

  • config structs in server/internal/config
  • bootstrap wiring in server/cmd/gestaltd and server/internal/bootstrap
  • HTTP routes in server/internal/server
  • deployment assets in server/Dockerfile and server/deploy/helm

The easiest way to make docs drift is to copy previous prose instead of reading the code path that actually implements the feature.

Useful Commands

go test ./...
 
gestaltd init --config ./config.yaml
gestaltd validate --config ./config.yaml
 
cd docs
npm ci
npm run typecheck
npm run build

Release Tags

Release workflows use scoped tags:

  • CLI: gestalt/v<version>
  • Server: gestaltd/v<version>
  • Go SDK: sdk/go/v<version>
  • Plugins: plugin/<plugin>/v<version>

Keep the bare semantic version aligned across artifacts when they are meant to ship together.

Adding New Built-Ins

If you add a new built-in auth provider, datastore, secret manager, binding, or named provider:

  1. register it in the relevant server/cmd/gestaltd file
  2. add or update tests
  3. update Built-in Plugins
  4. update any docs or examples that describe the supported inventory
Troubleshooting