Documentation
¶
Overview ¶
Package bundler provides Docker image generation tooling for Claude Code.
Index ¶
- Constants
- Variables
- func ContentHash(dockerfile []byte, includes []string, workDir string, embeddedScripts []string) (string, error)
- func CreateBuildContextFromDir(dir string, dockerfilePath string) (io.Reader, error)
- func EmbeddedScripts() []string
- func FlavorToImage(flavor string) string
- func LoadVersionsFile(path string) (*registry.VersionsFile, error)
- func SaveVersionsFile(path string, versions *registry.VersionsFile) error
- type ArgInstruction
- type CopyInstruction
- type DockerFileManagerOptions
- type DockerfileContext
- type DockerfileInject
- type DockerfileInstructions
- type DockerfileManager
- type FlavorOption
- type NetworkError
- type ProjectGenerator
- func (g *ProjectGenerator) Generate() ([]byte, error)
- func (g *ProjectGenerator) GenerateBuildContext() (io.Reader, error)
- func (g *ProjectGenerator) GenerateBuildContextFromDockerfile(dockerfile []byte) (io.Reader, error)
- func (g *ProjectGenerator) GetBuildContext() string
- func (g *ProjectGenerator) GetCustomDockerfilePath() string
- func (g *ProjectGenerator) UseCustomDockerfile() bool
- func (g *ProjectGenerator) WriteBuildContextToDir(dir string, dockerfile []byte) error
- type RegistryError
- type ResolveOptions
- type VariantConfig
- type VersionsManager
Constants ¶
const ( DefaultClaudeCodeVersion = "latest" DefaultUsername = "claude" DefaultShell = "/bin/zsh" // DefaultGoBuilderImage is the Go toolchain image used for builder stages. // Pinned to exact patch version + SHA digest matching go.mod (go 1.25.8). DefaultGoBuilderImage = "golang:1.25.8-alpine@sha256:8e02eb337d9e0ea459e041f1ee5eece41cbb61f1d83e7d883a3e2fb4862063fa" )
Default values for container configuration
const (
// ClaudeCodePackage is the npm package name for Claude Code.
ClaudeCodePackage = "@anthropic-ai/claude-code"
)
Variables ¶
var ( HostOpenScript = internals.HostOpenScript CallbackForwarderSource = internals.CallbackForwarderSource GitCredentialScript = internals.GitCredentialScript SocketForwarderSource = internals.SocketForwarderSource )
Re-export hostproxy container scripts from internal/hostproxy/internals. These were previously embedded directly in this package but now live alongside the hostproxy code they interact with.
var ( ErrVersionNotFound = registry.ErrVersionNotFound ErrInvalidVersion = registry.ErrInvalidVersion ErrNoVersions = registry.ErrNoVersions )
Re-export error types from registry for convenience.
var AgentPromptFile string
var ConfigFile string
var DockerfileTemplate string
var EntrypointScript string
var ErrNoBuildImage = errors.New("no build image configured: run 'clawker project init' or 'clawker init' to set up")
ErrNoBuildImage is returned when no build image is configured and no custom Dockerfile is specified.
var FirewallScript string
var SettingsFile string
var StatuslineScript string
Functions ¶
func ContentHash ¶
func ContentHash(dockerfile []byte, includes []string, workDir string, embeddedScripts []string) (string, error)
ContentHash computes a SHA-256 hash of the rendered Dockerfile bytes and include file contents, returning a 12-character hex prefix. This provides a content-addressed identifier for detecting when a rebuild is needed.
All include files must be readable. An error is returned if any file cannot be read (missing, permission denied, etc.).
func CreateBuildContextFromDir ¶
CreateBuildContextFromDir creates a tar archive from a directory for custom Dockerfiles.
func EmbeddedScripts ¶
func EmbeddedScripts() []string
EmbeddedScripts returns all embedded script contents for content hashing. Scripts are read dynamically from embed.FS to ensure new scripts are automatically included without manual list maintenance.
IMPORTANT: This function includes ALL scripts that affect the built image:
- Bundler assets (assets/*) are auto-discovered via embed.FS
- Hostproxy container scripts are included via internals.AllScripts()
New scripts added to either location will be automatically included. Scripts are sorted for deterministic hashing.
func FlavorToImage ¶
FlavorToImage maps a flavor name to its full Docker image reference. For known flavors, it returns the appropriate base image. For unknown flavors (custom images), it returns the input as-is.
func LoadVersionsFile ¶
func LoadVersionsFile(path string) (*registry.VersionsFile, error)
LoadVersionsFile loads a versions.json file from disk.
func SaveVersionsFile ¶
func SaveVersionsFile(path string, versions *registry.VersionsFile) error
SaveVersionsFile saves a versions.json file to disk.
Types ¶
type ArgInstruction ¶
ArgInstruction represents an ARG instruction.
type CopyInstruction ¶
CopyInstruction represents a COPY instruction.
type DockerFileManagerOptions ¶ added in v0.2.0
type DockerFileManagerOptions struct {
VariantCfg *VariantConfig
}
type DockerfileContext ¶
type DockerfileContext struct {
BaseImage string
Packages []string
Username string
UID int
GID int
Shell string
WorkspacePath string
ClaudeVersion string
IsAlpine bool
BuildKitEnabled bool
Instructions *DockerfileInstructions
Inject *DockerfileInject
// OTEL telemetry endpoints — populated from config.MonitoringConfig
OtelMetricsEndpoint string // e.g. "http://otel-collector:4318/v1/metrics"
OtelLogsEndpoint string // e.g. "http://otel-collector:4318/v1/logs"
OtelLogsExportInterval int // milliseconds, e.g. 5000
OtelMetricExportInterval int // milliseconds, e.g. 10000
// OTEL feature flags — populated from config.TelemetryConfig
OtelLogToolDetails bool // OTEL_LOG_TOOL_DETAILS=1
OtelLogUserPrompts bool // OTEL_LOG_USER_PROMPTS=1
OtelIncludeAccountUUID bool // OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true
OtelIncludeSessionID bool // OTEL_METRICS_INCLUDE_SESSION_ID=true
HasFirewallCA bool // CA cert exists for MITM inspection
GoBuilderImage string // Go toolchain image for builder stages (e.g. "golang:1.25.8-alpine@sha256:...")
}
DockerfileContext contains the template data for generating a Dockerfile. Only structural fields that affect the image filesystem are included here. Config-dependent values (env vars, labels, EXPOSE, VOLUME, HEALTHCHECK, SHELL) are injected at container creation time or via the Docker build API.
type DockerfileInject ¶
type DockerfileInject struct {
AfterFrom []string
AfterPackages []string
AfterUserSetup []string
AfterUserSwitch []string
AfterClaudeInstall []string
BeforeEntrypoint []string
}
DockerfileInject contains raw instruction injection points.
type DockerfileInstructions ¶
type DockerfileInstructions struct {
Copy []CopyInstruction
Args []ArgInstruction
UserRun []string
RootRun []string
}
DockerfileInstructions contains type-safe Dockerfile instructions. Only structural instructions that affect the image filesystem are included. Non-structural instructions (ENV, Labels, EXPOSE, VOLUME, HEALTHCHECK, SHELL) are injected at container creation time or via the Docker build API.
type DockerfileManager ¶
type DockerfileManager struct {
BuildKitEnabled bool // Enables --mount=type=cache directives in generated Dockerfiles
// contains filtered or unexported fields
}
DockerfileManager generates and persists Dockerfiles for each version/variant combination.
func NewDockerfileManager ¶
func NewDockerfileManager(cfg config.Config, opts *DockerFileManagerOptions) *DockerfileManager
NewDockerfileManager creates a new DockerfileManager.
func (*DockerfileManager) DockerfilesDir ¶
func (m *DockerfileManager) DockerfilesDir() (string, error)
DockerfilesDir returns the path to the dockerfiles directory. Delegates to cfg.DockerfilesSubdir() as the single source of truth.
func (*DockerfileManager) GenerateDockerfiles ¶
func (m *DockerfileManager) GenerateDockerfiles(versions *registry.VersionsFile) error
GenerateDockerfiles generates Dockerfiles for all version/variant combinations.
type FlavorOption ¶
FlavorOption represents a Linux flavor choice for image building.
func DefaultFlavorOptions ¶
func DefaultFlavorOptions() []FlavorOption
DefaultFlavorOptions returns the available Linux flavors for base images.
type NetworkError ¶
type NetworkError = registry.NetworkError
NetworkError is an alias for registry.NetworkError.
type ProjectGenerator ¶
type ProjectGenerator struct {
BuildKitEnabled bool // Enables --mount=type=cache directives in generated Dockerfiles
// contains filtered or unexported fields
}
ProjectGenerator creates Dockerfiles dynamically from project configuration (clawker.yaml).
func NewProjectGenerator ¶
func NewProjectGenerator(cfg config.Config, workDir string) *ProjectGenerator
NewProjectGenerator creates a new project Dockerfile generator.
func (*ProjectGenerator) Generate ¶
func (g *ProjectGenerator) Generate() ([]byte, error)
Generate creates a Dockerfile based on the project configuration.
func (*ProjectGenerator) GenerateBuildContext ¶
func (g *ProjectGenerator) GenerateBuildContext() (io.Reader, error)
GenerateBuildContext creates a tar archive containing the Dockerfile and scripts.
func (*ProjectGenerator) GenerateBuildContextFromDockerfile ¶
func (g *ProjectGenerator) GenerateBuildContextFromDockerfile(dockerfile []byte) (io.Reader, error)
GenerateBuildContextFromDockerfile builds a tar archive build context using pre-rendered Dockerfile bytes. This avoids re-generating the Dockerfile when the caller (e.g. EnsureImage) has already rendered it for content hashing.
func (*ProjectGenerator) GetBuildContext ¶
func (g *ProjectGenerator) GetBuildContext() string
GetBuildContext returns the build context path.
func (*ProjectGenerator) GetCustomDockerfilePath ¶
func (g *ProjectGenerator) GetCustomDockerfilePath() string
GetCustomDockerfilePath returns the path to the custom Dockerfile.
func (*ProjectGenerator) UseCustomDockerfile ¶
func (g *ProjectGenerator) UseCustomDockerfile() bool
UseCustomDockerfile checks if a custom Dockerfile should be used.
func (*ProjectGenerator) WriteBuildContextToDir ¶
func (g *ProjectGenerator) WriteBuildContextToDir(dir string, dockerfile []byte) error
WriteBuildContextToDir writes the Dockerfile and all supporting scripts to a directory on disk. BuildKit requires files on the filesystem (not a tar stream) because it creates fsutil.FS mounts from directory paths.
type RegistryError ¶
type RegistryError = registry.RegistryError
RegistryError is an alias for registry.RegistryError.
type ResolveOptions ¶
type ResolveOptions struct {
// Debug enables verbose output during resolution.
Debug bool
// Output is the writer for informational messages. Defaults to io.Discard if nil.
Output io.Writer
}
ResolveOptions configures version resolution behavior.
type VariantConfig ¶
type VariantConfig struct {
// DebianDefault is the default Debian variant (e.g., "trixie")
DebianDefault string
// AlpineDefault is the default Alpine variant (e.g., "alpine3.23")
AlpineDefault string
// Variants maps variant names to supported architectures
// e.g., {"trixie": ["amd64", "arm64v8"], "alpine3.23": ["amd64", "arm64v8"]}
Variants map[string][]string
// Arches is the list of all supported architectures
Arches []string
}
VariantConfig defines supported variants and architectures for Docker images.
func DefaultVariantConfig ¶
func DefaultVariantConfig() *VariantConfig
DefaultVariantConfig returns the default variant configuration. This matches the configuration from versions.sh.
func (*VariantConfig) IsAlpine ¶
func (c *VariantConfig) IsAlpine(variant string) bool
IsAlpine returns true if the variant is Alpine-based.
func (*VariantConfig) VariantNames ¶
func (c *VariantConfig) VariantNames() []string
VariantNames returns a slice of all variant names.
type VersionsManager ¶
type VersionsManager struct {
// contains filtered or unexported fields
}
VersionsManager handles version discovery and resolution for Claude Code.
func NewVersionsManager ¶
func NewVersionsManager() *VersionsManager
NewVersionsManager creates a new versions manager with default settings.
func NewVersionsManagerWithFetcher ¶
func NewVersionsManagerWithFetcher(fetcher registry.Fetcher, config *VariantConfig) *VersionsManager
NewVersionsManagerWithFetcher creates a versions manager with a custom fetcher. This is useful for testing with mock implementations.
func (*VersionsManager) ResolveVersions ¶
func (m *VersionsManager) ResolveVersions(ctx context.Context, patterns []string, opts ResolveOptions) (*registry.VersionsFile, error)
ResolveVersions resolves version patterns to full versions. Patterns can be:
- "latest", "stable", "next" - resolved via npm dist-tags
- "2.1" - partial match to highest 2.1.x release
- "2.1.2" - exact version match
Directories
¶
| Path | Synopsis |
|---|---|
|
Package registry provides clients for fetching package version information from npm and other registries.
|
Package registry provides clients for fetching package version information from npm and other registries. |
|
Package semver provides semantic versioning utilities with support for partial version matching (e.g., "2.1" matches "2.1.x").
|
Package semver provides semantic versioning utilities with support for partial version matching (e.g., "2.1" matches "2.1.x"). |