biucingcli 0.9.1__py3-none-any.whl

biucingcli/template_data/worker/template/Makefile

@@ -0,0 +1,105 @@
+APP_NAME={{WORKER_NAME}}
+WORKTREE_ROOT ?=$(shell git rev-parse --show-toplevel 2>/dev/null || pwd)
+WORKTREE_LABEL ?=$(shell basename "$(WORKTREE_ROOT)" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//; s/-$$//')
+WORKTREE_ID ?=$(shell printf '%s' "$(WORKTREE_ROOT)" | shasum | cut -c1-8)
+WORKTREE_SLUG ?=$(APP_NAME)-$(WORKTREE_ID)
+COMPOSE_PROJECT_NAME ?=$(WORKTREE_SLUG)
+IMAGE ?=$(WORKTREE_SLUG)
+TAG ?=dev
+IMAGE_REF := $(IMAGE):$(TAG)
+DEV_IMAGE ?=$(WORKTREE_SLUG)-dev
+DEV_TAG ?=dev
+DEV_IMAGE_REF := $(DEV_IMAGE):$(DEV_TAG)
+COMPOSE ?=COMPOSE_PROJECT_NAME=$(COMPOSE_PROJECT_NAME) docker compose
+DEV_COMPOSE_FILE ?=compose.dev.yaml
+DEV_SERVICE ?=app-dev
+GOPROXY ?=https://proxy.golang.org,direct
+GOSUMDB ?=sum.golang.org
+BUILDER_IMAGE ?=golang:1.26-alpine
+RUNTIME_IMAGE ?=alpine:3.20
+WORKER_RUN_MODE ?={{RUN_MODE}}
+WORKER_TICK_INTERVAL_SECONDS ?={{TICK_INTERVAL_SECONDS}}
+WORKER_SHUTDOWN_TIMEOUT_SECONDS ?={{SHUTDOWN_TIMEOUT_SECONDS}}
+WORKER_RETRY_MAX_ATTEMPTS ?=3
+WORKER_RETRY_INITIAL_BACKOFF_SECONDS ?=1
+WORKER_RETRY_MAX_BACKOFF_SECONDS ?=30
+GOCACHE ?= $(CURDIR)/.cache/go-build
+GOMODCACHE ?= $(CURDIR)/.cache/go-mod
+export COMPOSE_PROJECT_NAME
+export DEV_IMAGE
+export DEV_TAG
+export WORKER_RUN_MODE
+export WORKER_TICK_INTERVAL_SECONDS
+export WORKER_SHUTDOWN_TIMEOUT_SECONDS
+export WORKER_RETRY_MAX_ATTEMPTS
+export WORKER_RETRY_INITIAL_BACKOFF_SECONDS
+export WORKER_RETRY_MAX_BACKOFF_SECONDS
+export GOCACHE
+export GOMODCACHE
+
+.PHONY: worktree-info worktree-doctor worktree-compose-config clean-worktree bootstrap doctor dev dev-shell lint test verify run build clean help docker-build docker-run
+
+worktree-info:
+	@printf '%s\n' "Worktree root: $(WORKTREE_ROOT)"
+	@printf '%s\n' "Worktree label: $(WORKTREE_LABEL)"
+	@printf '%s\n' "Worktree ID: $(WORKTREE_ID)"
+	@printf '%s\n' "Worktree slug: $(WORKTREE_SLUG)"
+	@printf '%s\n' "Compose project: $(COMPOSE_PROJECT_NAME)"
+	@printf '%s\n' "Dev image ref: $(DEV_IMAGE_REF)"
+	@printf '%s\n' "Runtime image ref: $(IMAGE_REF)"
+	@printf '%s\n' "Go cache: $(GOCACHE)"
+	@printf '%s\n' "Go module cache: $(GOMODCACHE)"
+	@printf '%s\n' "Worker run mode: $(WORKER_RUN_MODE)"
+	@printf '%s\n' "Worker retry attempts: $(WORKER_RETRY_MAX_ATTEMPTS)"
+
+worktree-doctor:
+	@$(MAKE) --no-print-directory worktree-info
+	@case "$(GOCACHE)" in "$(WORKTREE_ROOT)"/*) ;; *) printf '%s\n' "GOCACHE should stay inside this worktree: $(GOCACHE)"; exit 1;; esac
+	@case "$(GOMODCACHE)" in "$(WORKTREE_ROOT)"/*) ;; *) printf '%s\n' "GOMODCACHE should stay inside this worktree: $(GOMODCACHE)"; exit 1;; esac
+	@printf '%s\n' "Worker has no published host ports by default."
+	@printf '%s\n' "Compose config check: make worktree-compose-config"
+
+worktree-compose-config:
+	@if ! command -v docker >/dev/null 2>&1; then printf '%s\n' "Docker is not available; cannot render Compose config."; exit 1; fi
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) config
+
+clean-worktree:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) down --remove-orphans --volumes
+
+bootstrap:
+	GOPROXY=$(GOPROXY) GOSUMDB=$(GOSUMDB) $(COMPOSE) -f $(DEV_COMPOSE_FILE) build $(DEV_SERVICE)
+
+doctor:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) ./scripts/doctor
+
+lint:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go vet ./...
+
+dev:
+	WORKER_RUN_MODE=$(WORKER_RUN_MODE) WORKER_TICK_INTERVAL_SECONDS=$(WORKER_TICK_INTERVAL_SECONDS) WORKER_SHUTDOWN_TIMEOUT_SECONDS=$(WORKER_SHUTDOWN_TIMEOUT_SECONDS) WORKER_RETRY_MAX_ATTEMPTS=$(WORKER_RETRY_MAX_ATTEMPTS) WORKER_RETRY_INITIAL_BACKOFF_SECONDS=$(WORKER_RETRY_INITIAL_BACKOFF_SECONDS) WORKER_RETRY_MAX_BACKOFF_SECONDS=$(WORKER_RETRY_MAX_BACKOFF_SECONDS) GOPROXY=$(GOPROXY) GOSUMDB=$(GOSUMDB) $(COMPOSE) -f $(DEV_COMPOSE_FILE) up $(DEV_SERVICE)
+
+dev-shell:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) sh
+
+test:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go test ./...
+
+verify: doctor lint test build
+
+run:
+	WORKER_RUN_MODE=$(WORKER_RUN_MODE) WORKER_TICK_INTERVAL_SECONDS=$(WORKER_TICK_INTERVAL_SECONDS) WORKER_SHUTDOWN_TIMEOUT_SECONDS=$(WORKER_SHUTDOWN_TIMEOUT_SECONDS) WORKER_RETRY_MAX_ATTEMPTS=$(WORKER_RETRY_MAX_ATTEMPTS) WORKER_RETRY_INITIAL_BACKOFF_SECONDS=$(WORKER_RETRY_INITIAL_BACKOFF_SECONDS) WORKER_RETRY_MAX_BACKOFF_SECONDS=$(WORKER_RETRY_MAX_BACKOFF_SECONDS) $(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE)
+
+build:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go build -o bin/$(APP_NAME) ./cmd/worker
+
+clean:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) down --remove-orphans
+
+help:
+	@printf '%s\n' "Common commands:" "  make bootstrap  Prepare the development environment" "  make doctor     Check required tools and project configuration" "  make lint       Run static analysis" "  make test       Run tests" "  make verify     Run the complete local verification contract" "  make build      Build the application" "  make clean      Remove generated runtime state" "  make help       Show this command summary"
+
+docker-build:
+	docker build --build-arg BUILDER_IMAGE=$(BUILDER_IMAGE) --build-arg RUNTIME_IMAGE=$(RUNTIME_IMAGE) --build-arg GOPROXY=$(GOPROXY) --build-arg GOSUMDB=$(GOSUMDB) -t $(IMAGE_REF) .
+
+docker-run:
+	docker run --rm -e WORKER_RUN_MODE=$(WORKER_RUN_MODE) -e WORKER_TICK_INTERVAL_SECONDS=$(WORKER_TICK_INTERVAL_SECONDS) -e WORKER_SHUTDOWN_TIMEOUT_SECONDS=$(WORKER_SHUTDOWN_TIMEOUT_SECONDS) -e WORKER_RETRY_MAX_ATTEMPTS=$(WORKER_RETRY_MAX_ATTEMPTS) -e WORKER_RETRY_INITIAL_BACKOFF_SECONDS=$(WORKER_RETRY_INITIAL_BACKOFF_SECONDS) -e WORKER_RETRY_MAX_BACKOFF_SECONDS=$(WORKER_RETRY_MAX_BACKOFF_SECONDS) $(IMAGE_REF)

biucingcli/template_data/worker/template/README.md

@@ -0,0 +1,164 @@
+# {{WORKER_NAME}}
+
+This project was generated by BiucingCLI.
+
+## Stack
+
+- Go
+- Docker
+
+## Project Layout
+
+- `cmd/worker`: background process entrypoint
+- `internal/config`: config loading and environment overrides
+- `internal/runtime`: execution loop and graceful shutdown behavior
+- `internal/task`: starter task implementation
+- `configs`: local config files
+- `tests`: generated-project runtime tests
+
+## Worker Shape
+
+This starter is intentionally narrow:
+
+- it is designed for background execution rather than a public HTTP API;
+- it supports `scheduled` and `oneshot` execution modes;
+- it keeps operational basics such as config loading, logging, and graceful shutdown explicit.
+
+The default config file is `configs/config.json`.
+
+## Docker Workflow
+
+```bash
+make bootstrap
+make dev
+```
+
+The starter is designed to run development, checks, and runtime packaging inside Docker by default.
+
+## Available Commands
+
+```bash
+make bootstrap
+make dev
+make dev-shell
+make doctor
+make lint
+make test
+make verify
+make build
+make docker-build
+make docker-run
+make clean
+make help
+```
+
+## Execution Modes
+
+- `scheduled`: runs the starter task immediately and then on a repeating interval
+- `oneshot`: runs the starter task once and exits
+
+Each execution cycle has explicit retry semantics:
+
+- `retry_max_attempts` includes the initial attempt; set it to `1` to disable retries.
+- failed attempts use exponential backoff from `retry_initial_backoff_seconds`, capped by `retry_max_backoff_seconds`.
+- `oneshot` returns the final error after retries are exhausted, so the process exits non-zero.
+- `scheduled` logs an exhausted cycle, waits one `tick_interval_seconds` fixed delay, and starts the next cycle.
+- cancellation interrupts scheduled waits and retry backoff immediately. An active task receives a canceled context and has `shutdown_timeout_seconds` to return before shutdown fails.
+
+The generated defaults are:
+
+- `run_mode={{RUN_MODE}}`
+- `tick_interval_seconds={{TICK_INTERVAL_SECONDS}}`
+- `shutdown_timeout_seconds={{SHUTDOWN_TIMEOUT_SECONDS}}`
+- `retry_max_attempts=3`
+- `retry_initial_backoff_seconds=1`
+- `retry_max_backoff_seconds=30`
+
+You can override them with environment variables:
+
+- `WORKER_NAME`
+- `WORKER_RUN_MODE`
+- `WORKER_TICK_INTERVAL_SECONDS`
+- `WORKER_SHUTDOWN_TIMEOUT_SECONDS`
+- `WORKER_RETRY_MAX_ATTEMPTS`
+- `WORKER_RETRY_INITIAL_BACKOFF_SECONDS`
+- `WORKER_RETRY_MAX_BACKOFF_SECONDS`
+- `CONFIG_FILE`
+
+Example oneshot run:
+
+```bash
+WORKER_RUN_MODE=oneshot make run
+```
+
+Example scheduled run with a shorter loop:
+
+```bash
+WORKER_RUN_MODE=scheduled WORKER_TICK_INTERVAL_SECONDS=5 make dev
+```
+
+## Environment
+
+- `Brewfile`: optional host workstation tool installation
+- `.mise.toml`: pinned Go version for host workflows
+- `Dockerfile.dev`: development image used by Docker Compose
+- `compose.dev.yaml`: local Docker development workflow
+- `scripts/bootstrap`: host-oriented setup helper when you do not use Docker
+- `scripts/doctor`: local environment checks
+
+## Runtime Packaging
+
+Build the runtime image:
+
+```bash
+make docker-build
+```
+
+Run the runtime image with the default scheduled mode:
+
+```bash
+make docker-run
+```
+
+Run the runtime image once and exit:
+
+```bash
+make docker-run WORKER_RUN_MODE=oneshot
+```
+
+The runtime image defaults are:
+
+- `BUILDER_IMAGE=golang:1.26-alpine`
+- `RUNTIME_IMAGE=alpine:3.20`
+
+## Worktree Workflow
+
+This starter is safe to run from parallel Git worktrees without publishing host ports by default.
+
+```bash
+make worktree-info
+make worktree-doctor
+make worktree-compose-config
+make dev
+make clean-worktree
+```
+
+- `WORKTREE_LABEL` is derived from the worktree directory name for display.
+- `WORKTREE_ID` is derived from the current worktree path by default and can be overridden.
+- `COMPOSE_PROJECT_NAME` defaults to `{{WORKER_NAME}}-$(WORKTREE_ID)`, so Compose containers, networks, and cache volumes stay scoped to the worktree.
+- `DEV_IMAGE` and `IMAGE` default to worktree-specific names so dev/runtime image tags do not overwrite another worktree by default.
+- `GOCACHE` and `GOMODCACHE` stay under the current worktree's `.cache/` directory.
+- The Docker dev workflow mounts Go build and module caches as Compose-scoped volumes, so dependency versions and downloads do not bleed across worktrees.
+- `make worktree-compose-config` renders the current worktree's Compose config without starting containers.
+- `make clean-worktree` removes only the current worktree's Compose containers, networks, and volumes.
+
+## Validation
+
+The generated project includes:
+
+- config-loading tests under `internal/config`
+- runtime-loop tests under `internal/runtime`
+- deterministic retry, fixed-delay scheduling, cancellation, and shutdown-timeout tests using an injected clock; they do not sleep to advance worker time
+- a generated-project test under `tests/worker_test.go`
+
+`make verify` runs the local doctor checks plus `go test ./...` inside Docker.

biucingcli/template_data/worker/template/cmd/worker/main.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"{{MODULE_NAME}}/internal/config"
+	"{{MODULE_NAME}}/internal/runtime"
+	"{{MODULE_NAME}}/internal/task"
+)
+
+func main() {
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("load config: %v", err)
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	logger := log.New(os.Stdout, "", log.LstdFlags)
+	runner := runtime.New(runtime.Options{
+		Name:            cfg.Worker.Name,
+		Mode:            cfg.Worker.RunMode,
+		TickInterval:    time.Duration(cfg.Worker.TickIntervalSeconds) * time.Second,
+		ShutdownTimeout: time.Duration(cfg.Worker.ShutdownTimeoutSeconds) * time.Second,
+		MaxAttempts:     cfg.Worker.RetryMaxAttempts,
+		InitialBackoff:  time.Duration(cfg.Worker.RetryInitialSeconds) * time.Second,
+		MaxBackoff:      time.Duration(cfg.Worker.RetryMaxSeconds) * time.Second,
+		Executor:        task.NewHeartbeatTask(cfg.Worker.Name),
+		Logger:          logger,
+	})
+
+	if err := runner.Run(ctx); err != nil {
+		log.Fatalf("run worker: %v", err)
+	}
+}

biucingcli/template_data/worker/template/compose.dev.yaml

@@ -0,0 +1,29 @@
+services:
+  app-dev:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+      args:
+        GOPROXY: ${GOPROXY:-https://proxy.golang.org,direct}
+        GOSUMDB: ${GOSUMDB:-sum.golang.org}
+    image: ${DEV_IMAGE:-{{WORKER_NAME}}-dev}:${DEV_TAG:-latest}
+    working_dir: /app
+    environment:
+      CONFIG_FILE: configs/config.json
+      WORKER_RUN_MODE: ${WORKER_RUN_MODE:-{{RUN_MODE}}}
+      WORKER_TICK_INTERVAL_SECONDS: ${WORKER_TICK_INTERVAL_SECONDS:-{{TICK_INTERVAL_SECONDS}}}
+      WORKER_SHUTDOWN_TIMEOUT_SECONDS: ${WORKER_SHUTDOWN_TIMEOUT_SECONDS:-{{SHUTDOWN_TIMEOUT_SECONDS}}}
+      WORKER_RETRY_MAX_ATTEMPTS: ${WORKER_RETRY_MAX_ATTEMPTS:-3}
+      WORKER_RETRY_INITIAL_BACKOFF_SECONDS: ${WORKER_RETRY_INITIAL_BACKOFF_SECONDS:-1}
+      WORKER_RETRY_MAX_BACKOFF_SECONDS: ${WORKER_RETRY_MAX_BACKOFF_SECONDS:-30}
+      GOCACHE: /cache/go-build
+      GOMODCACHE: /cache/go-mod
+    volumes:
+      - .:/app
+      - worker-go-build-cache:/cache/go-build
+      - worker-go-mod-cache:/cache/go-mod
+    command: sh -lc "go run ./cmd/worker"
+
+volumes:
+  worker-go-build-cache:
+  worker-go-mod-cache:

biucingcli/template_data/worker/template/configs/config.json

@@ -0,0 +1,11 @@
+{
+  "worker": {
+    "name": "{{WORKER_NAME}}",
+    "run_mode": "{{RUN_MODE}}",
+    "tick_interval_seconds": {{TICK_INTERVAL_SECONDS}},
+    "shutdown_timeout_seconds": {{SHUTDOWN_TIMEOUT_SECONDS}},
+    "retry_max_attempts": 3,
+    "retry_initial_backoff_seconds": 1,
+    "retry_max_backoff_seconds": 30
+  }
+}

biucingcli/template_data/worker/template/go.mod

@@ -0,0 +1,3 @@
+module {{MODULE_NAME}}
+
+go 1.26.0

biucingcli/template_data/worker/template/go.sum

@@ -0,0 +1 @@
+

biucingcli/template_data/worker/template/internal/config/config.go

@@ -0,0 +1,108 @@
+package config
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"strconv"
+)
+
+const defaultConfigFile = "configs/config.json"
+
+type Config struct {
+	Worker WorkerConfig `json:"worker"`
+}
+
+type WorkerConfig struct {
+	Name                   string `json:"name"`
+	RunMode                string `json:"run_mode"`
+	TickIntervalSeconds    int    `json:"tick_interval_seconds"`
+	ShutdownTimeoutSeconds int    `json:"shutdown_timeout_seconds"`
+	RetryMaxAttempts       int    `json:"retry_max_attempts"`
+	RetryInitialSeconds    int    `json:"retry_initial_backoff_seconds"`
+	RetryMaxSeconds        int    `json:"retry_max_backoff_seconds"`
+}
+
+func Load() (Config, error) {
+	configFile := os.Getenv("CONFIG_FILE")
+	if configFile == "" {
+		configFile = defaultConfigFile
+	}
+
+	data, err := os.ReadFile(configFile)
+	if err != nil {
+		return Config{}, err
+	}
+
+	var cfg Config
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return Config{}, err
+	}
+
+	applyStringOverride("WORKER_NAME", &cfg.Worker.Name)
+	applyStringOverride("WORKER_RUN_MODE", &cfg.Worker.RunMode)
+	if err := applyIntOverride("WORKER_TICK_INTERVAL_SECONDS", &cfg.Worker.TickIntervalSeconds); err != nil {
+		return Config{}, err
+	}
+	if err := applyIntOverride("WORKER_SHUTDOWN_TIMEOUT_SECONDS", &cfg.Worker.ShutdownTimeoutSeconds); err != nil {
+		return Config{}, err
+	}
+	if err := applyIntOverride("WORKER_RETRY_MAX_ATTEMPTS", &cfg.Worker.RetryMaxAttempts); err != nil {
+		return Config{}, err
+	}
+	if err := applyIntOverride("WORKER_RETRY_INITIAL_BACKOFF_SECONDS", &cfg.Worker.RetryInitialSeconds); err != nil {
+		return Config{}, err
+	}
+	if err := applyIntOverride("WORKER_RETRY_MAX_BACKOFF_SECONDS", &cfg.Worker.RetryMaxSeconds); err != nil {
+		return Config{}, err
+	}
+
+	if cfg.Worker.Name == "" {
+		return Config{}, errors.New("worker.name is required")
+	}
+	if cfg.Worker.RunMode == "" {
+		cfg.Worker.RunMode = "{{RUN_MODE}}"
+	}
+	if cfg.Worker.RunMode != "scheduled" && cfg.Worker.RunMode != "oneshot" {
+		return Config{}, errors.New("worker.run_mode must be one of: scheduled, oneshot")
+	}
+	if cfg.Worker.TickIntervalSeconds <= 0 {
+		cfg.Worker.TickIntervalSeconds = {{TICK_INTERVAL_SECONDS}}
+	}
+	if cfg.Worker.ShutdownTimeoutSeconds <= 0 {
+		cfg.Worker.ShutdownTimeoutSeconds = {{SHUTDOWN_TIMEOUT_SECONDS}}
+	}
+	if cfg.Worker.RetryMaxAttempts <= 0 {
+		cfg.Worker.RetryMaxAttempts = 3
+	}
+	if cfg.Worker.RetryInitialSeconds <= 0 {
+		cfg.Worker.RetryInitialSeconds = 1
+	}
+	if cfg.Worker.RetryMaxSeconds <= 0 {
+		cfg.Worker.RetryMaxSeconds = 30
+	}
+	if cfg.Worker.RetryMaxSeconds < cfg.Worker.RetryInitialSeconds {
+		return Config{}, errors.New("worker.retry_max_backoff_seconds must be greater than or equal to worker.retry_initial_backoff_seconds")
+	}
+
+	return cfg, nil
+}
+
+func applyStringOverride(envKey string, target *string) {
+	if value := os.Getenv(envKey); value != "" {
+		*target = value
+	}
+}
+
+func applyIntOverride(envKey string, target *int) error {
+	value := os.Getenv(envKey)
+	if value == "" {
+		return nil
+	}
+	parsed, err := strconv.Atoi(value)
+	if err != nil {
+		return errors.New(envKey + " must be an integer")
+	}
+	*target = parsed
+	return nil
+}

biucingcli/template_data/worker/template/internal/config/config_test.go

@@ -0,0 +1,86 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadDefaults(t *testing.T) {
+	tempDir := t.TempDir()
+	configPath := filepath.Join(tempDir, "config.json")
+	if err := os.WriteFile(configPath, []byte(`{"worker":{"name":"demo-worker","run_mode":"scheduled","tick_interval_seconds":15,"shutdown_timeout_seconds":8}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Setenv("CONFIG_FILE", configPath)
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if cfg.Worker.Name != "demo-worker" {
+		t.Fatalf("expected worker name %q, got %q", "demo-worker", cfg.Worker.Name)
+	}
+	if cfg.Worker.RunMode != "scheduled" {
+		t.Fatalf("expected run mode %q, got %q", "scheduled", cfg.Worker.RunMode)
+	}
+	if cfg.Worker.TickIntervalSeconds != 15 {
+		t.Fatalf("expected tick interval %d, got %d", 15, cfg.Worker.TickIntervalSeconds)
+	}
+	if cfg.Worker.RetryMaxAttempts != 3 || cfg.Worker.RetryInitialSeconds != 1 || cfg.Worker.RetryMaxSeconds != 30 {
+		t.Fatalf("unexpected retry defaults: %+v", cfg.Worker)
+	}
+}
+
+func TestLoadUsesEnvironmentOverrides(t *testing.T) {
+	tempDir := t.TempDir()
+	configPath := filepath.Join(tempDir, "config.json")
+	if err := os.WriteFile(configPath, []byte(`{"worker":{"name":"demo-worker","run_mode":"scheduled","tick_interval_seconds":15,"shutdown_timeout_seconds":8}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Setenv("CONFIG_FILE", configPath)
+	t.Setenv("WORKER_NAME", "override-worker")
+	t.Setenv("WORKER_RUN_MODE", "oneshot")
+	t.Setenv("WORKER_TICK_INTERVAL_SECONDS", "3")
+	t.Setenv("WORKER_SHUTDOWN_TIMEOUT_SECONDS", "2")
+	t.Setenv("WORKER_RETRY_MAX_ATTEMPTS", "5")
+	t.Setenv("WORKER_RETRY_INITIAL_BACKOFF_SECONDS", "2")
+	t.Setenv("WORKER_RETRY_MAX_BACKOFF_SECONDS", "8")
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if cfg.Worker.Name != "override-worker" {
+		t.Fatalf("expected worker name %q, got %q", "override-worker", cfg.Worker.Name)
+	}
+	if cfg.Worker.RunMode != "oneshot" {
+		t.Fatalf("expected run mode %q, got %q", "oneshot", cfg.Worker.RunMode)
+	}
+	if cfg.Worker.TickIntervalSeconds != 3 {
+		t.Fatalf("expected tick interval %d, got %d", 3, cfg.Worker.TickIntervalSeconds)
+	}
+	if cfg.Worker.ShutdownTimeoutSeconds != 2 {
+		t.Fatalf("expected shutdown timeout %d, got %d", 2, cfg.Worker.ShutdownTimeoutSeconds)
+	}
+	if cfg.Worker.RetryMaxAttempts != 5 || cfg.Worker.RetryInitialSeconds != 2 || cfg.Worker.RetryMaxSeconds != 8 {
+		t.Fatalf("unexpected retry overrides: %+v", cfg.Worker)
+	}
+}
+
+func TestLoadRejectsRetryBackoffRange(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	data := []byte(`{"worker":{"name":"demo-worker","retry_initial_backoff_seconds":10,"retry_max_backoff_seconds":2}}`)
+	if err := os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("CONFIG_FILE", configPath)
+
+	if _, err := Load(); err == nil {
+		t.Fatal("expected retry backoff range validation to fail")
+	}
+}