bundler

package
v0.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 3, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package bundler provides Docker image generation tooling for Claude Code.

Index

Constants

View Source
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

View Source
const (
	// ClaudeCodePackage is the npm package name for Claude Code.
	ClaudeCodePackage = "@anthropic-ai/claude-code"
)

Variables

View Source
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.

View Source
var (
	ErrVersionNotFound = registry.ErrVersionNotFound
	ErrInvalidVersion  = registry.ErrInvalidVersion
	ErrNoVersions      = registry.ErrNoVersions
)

Re-export error types from registry for convenience.

View Source
var AgentPromptFile string
View Source
var ConfigFile string
View Source
var DockerfileTemplate string
View Source
var EntrypointScript string
View Source
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.

View Source
var FirewallScript string
View Source
var SettingsFile string
View Source
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

func CreateBuildContextFromDir(dir string, dockerfilePath string) (io.Reader, error)

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

func FlavorToImage(flavor string) string

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

type ArgInstruction struct {
	Name    string
	Default string
}

ArgInstruction represents an ARG instruction.

type CopyInstruction

type CopyInstruction struct {
	Src   string
	Dest  string
	Chown string
	Chmod string
}

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

type FlavorOption struct {
	Name        string
	Description string
}

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").

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL