biucingcli 0.9.1__py3-none-any.whl

biucingcli/template_data/microservice/template/tests/server_test.go

@@ -0,0 +1,153 @@
+package tests
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	servicev1 "{{MODULE_NAME}}/api/gen/go/service/v1"
+	"{{MODULE_NAME}}/internal/config"
+	"{{MODULE_NAME}}/internal/model"
+	"{{MODULE_NAME}}/internal/router"
+	"{{MODULE_NAME}}/internal/service"
+	"{{MODULE_NAME}}/internal/transport"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/test/bufconn"
+)
+
+func TestHealthz(t *testing.T) {
+	engine := router.New(config.Config{
+		Service: config.ServiceConfig{
+			Name:     "{{SERVICE_NAME}}",
+			HTTPPort: "{{HTTP_PORT}}",
+			GRPCPort: "{{GRPC_PORT}}",
+		},
+		Store: config.StoreConfig{
+			Driver: "{{DEPENDENCY_STORE}}",
+		},
+	})
+
+	request := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	recorder := httptest.NewRecorder()
+
+	engine.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, recorder.Code)
+	}
+
+	var response model.HealthResponse
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+
+	if response.Service != "{{SERVICE_NAME}}" {
+		t.Fatalf("expected service %q, got %q", "{{SERVICE_NAME}}", response.Service)
+	}
+
+	if response.Store != "{{DEPENDENCY_STORE}}" {
+		t.Fatalf("expected store %q, got %q", "{{DEPENDENCY_STORE}}", response.Store)
+	}
+}
+
+func TestPing(t *testing.T) {
+	engine := router.New(config.Config{
+		Service: config.ServiceConfig{
+			Name:     "{{SERVICE_NAME}}",
+			HTTPPort: "{{HTTP_PORT}}",
+			GRPCPort: "{{GRPC_PORT}}",
+		},
+		Store: config.StoreConfig{
+			Driver: "{{DEPENDENCY_STORE}}",
+		},
+	})
+
+	request := httptest.NewRequest(http.MethodGet, "/api/v1/ping", nil)
+	recorder := httptest.NewRecorder()
+
+	engine.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, recorder.Code)
+	}
+
+	var response model.PingResponse
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+
+	if response.Message != "pong" {
+		t.Fatalf("expected message %q, got %q", "pong", response.Message)
+	}
+
+	if response.ProtoPackage != "{{PROTO_PACKAGE}}" {
+		t.Fatalf("expected proto package %q, got %q", "{{PROTO_PACKAGE}}", response.ProtoPackage)
+	}
+}
+
+func TestGRPCPingContract(t *testing.T) {
+	listener := bufconn.Listen(1024 * 1024)
+	pingService := service.NewPingService("{{SERVICE_NAME}}", "{{PROTO_PACKAGE}}")
+	server := transport.NewGRPCServer("{{SERVICE_NAME}}", pingService)
+
+	go func() {
+		_ = server.Serve(listener)
+	}()
+	t.Cleanup(func() {
+		server.Stop()
+		_ = listener.Close()
+	})
+
+	connection, err := grpc.NewClient(
+		"passthrough:///bufnet",
+		grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) {
+			return listener.Dial()
+		}),
+		grpc.WithTransportCredentials(insecure.NewCredentials()),
+	)
+	if err != nil {
+		t.Fatalf("create gRPC client: %v", err)
+	}
+	t.Cleanup(func() { _ = connection.Close() })
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	client := servicev1.New{{SERVICE_TYPE_NAME}}ServiceClient(connection)
+	healthClient := healthpb.NewHealthClient(connection)
+	healthResponse, err := healthClient.Check(ctx, &healthpb.HealthCheckRequest{Service: "{{SERVICE_NAME}}"})
+	if err != nil {
+		t.Fatalf("check gRPC health: %v", err)
+	}
+	if healthResponse.GetStatus() != healthpb.HealthCheckResponse_SERVING {
+		t.Fatalf("expected gRPC health status SERVING, got %s", healthResponse.GetStatus())
+	}
+
+	response, err := client.Ping(ctx, &servicev1.PingRequest{RequestId: "contract-test"})
+	if err != nil {
+		t.Fatalf("call Ping: %v", err)
+	}
+
+	if response.GetMessage() != "pong" {
+		t.Fatalf("expected message %q, got %q", "pong", response.GetMessage())
+	}
+	if response.GetService() != "{{SERVICE_NAME}}" {
+		t.Fatalf("expected service %q, got %q", "{{SERVICE_NAME}}", response.GetService())
+	}
+
+	expectedMethod := "/{{PROTO_PACKAGE}}.{{SERVICE_TYPE_NAME}}Service/Ping"
+	if servicev1.{{SERVICE_TYPE_NAME}}Service_Ping_FullMethodName != expectedMethod {
+		t.Fatalf(
+			"expected full method %q, got %q",
+			expectedMethod,
+			servicev1.{{SERVICE_TYPE_NAME}}Service_Ping_FullMethodName,
+		)
+	}
+}

biucingcli/template_data/microservice/template.json

@@ -0,0 +1,114 @@
+{
+  "name": "microservice",
+  "description": "Go microservice starter with Protobuf, Buf, Compose, and OpenTelemetry",
+  "category": "backend",
+  "stack": ["Go", "Gin", "Protobuf", "Buf", "Docker Compose", "OpenTelemetry"],
+  "tags": ["grpc", "otel", "protobuf", "docker", "service"],
+  "platforms": ["linux", "container"],
+  "maturity": {
+    "level": "validated",
+    "summary": "Containerized microservice starter with coordinated HTTP/gRPC shutdown, bounded timeouts, health checks, protobuf, and observability."
+  },
+  "validation": {
+    "status": "real-build-verified",
+    "verification_tier": "real-build",
+    "evidence": [
+      "python unittest template rendering coverage",
+      "generated-project HTTP and gRPC shutdown tests",
+      "HTTP and gRPC health checks",
+      "real docker runtime image builds",
+      "real docker development image builds"
+    ]
+  },
+  "operating_assumptions": [
+    "The starter assumes a contract-first backend workflow with Buf and local dependency orchestration.",
+    "Generated projects are expected to validate protobuf, service runtime, and container packaging together."
+  ],
+  "workflow_labels": ["bootstrap", "dev", "verify", "build", "runtime"],
+  "commands": {
+    "bootstrap": "make bootstrap",
+    "doctor": "make doctor",
+    "lint": "make lint",
+    "test": "make test",
+    "verify": "make verify",
+    "build": "make build",
+    "clean": "make clean",
+    "help": "make help"
+  },
+  "worktree": {
+    "support_level": "worktree-ready",
+    "isolation_dimensions": [
+      "runtime-names",
+      "ports",
+      "dependency-stores",
+      "caches",
+      "generated-output",
+      "cleanup",
+      "diagnostics"
+    ],
+    "diagnostics": [
+      "make worktree-info",
+      "make worktree-doctor"
+    ],
+    "cleanup": [
+      "make clean-worktree"
+    ]
+  },
+  "variables": [
+    {
+      "name": "project_name",
+      "required": true,
+      "validator": "project-name"
+    },
+    {
+      "name": "module_name",
+      "required": true,
+      "prompt": "Go module name: ",
+      "validator": "go-module"
+    },
+    {
+      "name": "service_name",
+      "required": false,
+      "default_from": "project_name",
+      "validator": "slug"
+    },
+    {
+      "name": "proto_package",
+      "required": true,
+      "prompt": "Proto package: ",
+      "validator": "protobuf-package"
+    },
+    {
+      "name": "http_port",
+      "required": false,
+      "default": "8080",
+      "validator": "port"
+    },
+    {
+      "name": "grpc_port",
+      "required": false,
+      "default": "9090",
+      "validator": "port"
+    },
+    {
+      "name": "dependency_store",
+      "required": false,
+      "default": "postgres",
+      "validator": "choice",
+      "choices": ["postgres", "redis"]
+    },
+    {
+      "name": "otel_exporter_endpoint",
+      "required": false,
+      "default": "http://localhost:4318",
+      "validator": "url"
+    }
+  ],
+  "next_steps": [
+    "make bootstrap",
+    "make dev",
+    "make verify",
+    "make up",
+    "make docker-build"
+  ]
+}

biucingcli/template_data/web-service/template/.air.toml

@@ -0,0 +1,11 @@
+root = "."
+tmp_dir = "tmp"
+
+[build]
+cmd = "go build -o ./tmp/server ./cmd/server"
+bin = "./tmp/server"
+exclude_dir = [".git", ".cache", "bin", "tmp"]
+include_ext = ["go", "yaml"]
+
+[log]
+time = true

biucingcli/template_data/web-service/template/.dockerignore

@@ -0,0 +1,5 @@
+.git/
+.cache/
+bin/
+tmp/
+.DS_Store

biucingcli/template_data/web-service/template/.gitignore

@@ -0,0 +1,5 @@
+bin/
+dist/
+.cache/
+.DS_Store
+coverage.out

biucingcli/template_data/web-service/template/.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+go = "1.26.0"

biucingcli/template_data/web-service/template/Brewfile

@@ -0,0 +1,5 @@
+brew "mise"
+brew "go"
+brew "golangci-lint"
+brew "gh"
+brew "jq"

biucingcli/template_data/web-service/template/Dockerfile

@@ -0,0 +1,41 @@
+ARG BUILDER_IMAGE=golang:1.26-alpine
+ARG RUNTIME_IMAGE=alpine:3.20
+
+FROM ${BUILDER_IMAGE} AS builder
+
+WORKDIR /app
+
+ARG GOPROXY=https://proxy.golang.org,direct
+ARG GOSUMDB=sum.golang.org
+ENV GOPROXY=${GOPROXY}
+ENV GOSUMDB=${GOSUMDB}
+
+COPY go.mod ./
+RUN set -eux; \
+    attempt=1; \
+    until go mod download; do \
+      if [ "$attempt" -ge 3 ]; then \
+        exit 1; \
+      fi; \
+      attempt=$((attempt + 1)); \
+      sleep 5; \
+    done
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH:-amd64} go build -o /out/server ./cmd/server
+
+FROM ${RUNTIME_IMAGE}
+
+WORKDIR /app
+
+COPY --from=builder /out/server /app/server
+COPY configs/config.yaml /app/configs/config.yaml
+
+EXPOSE {{HTTP_PORT}}
+
+ENV CONFIG_FILE=/app/configs/config.yaml
+
+HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
+    CMD ["/app/server", "healthcheck", "http://127.0.0.1:{{HTTP_PORT}}/healthz"]
+
+CMD ["/app/server"]

biucingcli/template_data/web-service/template/Dockerfile.dev

@@ -0,0 +1,45 @@
+FROM golang:1.26-bookworm
+
+WORKDIR /workspace
+
+ARG AIR_VERSION=1.65.3
+ARG GOLANGCI_LINT_VERSION=2.12.2
+ARG GOPROXY=https://proxy.golang.org,direct
+ARG GOSUMDB=sum.golang.org
+ARG TARGETARCH
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends bash ca-certificates curl git make tar \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+      arm64) air_arch="arm64"; golangci_arch="arm64" ;; \
+      amd64) air_arch="amd64"; golangci_arch="amd64" ;; \
+      *) echo "Unsupported TARGETARCH: ${TARGETARCH}"; exit 1 ;; \
+    esac; \
+    curl -fsSL "https://github.com/air-verse/air/releases/download/v${AIR_VERSION}/air_${AIR_VERSION}_linux_${air_arch}.tar.gz" \
+      | tar -xz -C /usr/local/bin air; \
+    curl -fsSL "https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/golangci-lint-${GOLANGCI_LINT_VERSION}-linux-${golangci_arch}.tar.gz" \
+      | tar -xz -C /tmp; \
+    mv "/tmp/golangci-lint-${GOLANGCI_LINT_VERSION}-linux-${golangci_arch}/golangci-lint" /usr/local/bin/golangci-lint; \
+    rm -rf /tmp/golangci-lint-${GOLANGCI_LINT_VERSION}-linux-${golangci_arch}
+
+COPY go.mod go.sum ./
+ENV GOPROXY=${GOPROXY}
+ENV GOSUMDB=${GOSUMDB}
+RUN set -eux; \
+    attempt=1; \
+    until go mod download; do \
+      if [ "$attempt" -ge 3 ]; then \
+        exit 1; \
+      fi; \
+      attempt=$((attempt + 1)); \
+      sleep 5; \
+    done
+
+ENV PATH="/go/bin:${PATH}"
+ENV GOCACHE=/workspace/.cache/go-build
+ENV GOLANGCI_LINT_CACHE=/workspace/.cache/golangci-lint
+
+CMD ["air", "-c", ".air.toml"]

biucingcli/template_data/web-service/template/Makefile

@@ -0,0 +1,113 @@
+APP_NAME={{SERVICE_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)
+COMPOSE ?=COMPOSE_PROJECT_NAME=$(COMPOSE_PROJECT_NAME) docker compose
+CONTAINER_PORT ?={{HTTP_PORT}}
+HOST_PORT ?={{HTTP_PORT}}
+DEV_COMPOSE_FILE ?=compose.dev.yaml
+DEV_SERVICE ?=app-dev
+DOCKER_VARIANT ?=alpine
+DOCKER_PLATFORM ?=linux/arm64
+GOPROXY ?=https://proxy.golang.org,direct
+GOSUMDB ?=sum.golang.org
+GOCACHE ?= $(CURDIR)/.cache/go-build
+GOMODCACHE ?= $(CURDIR)/.cache/go-mod
+GOLANGCI_LINT_CACHE ?= $(CURDIR)/.cache/golangci-lint
+export COMPOSE_PROJECT_NAME
+export IMAGE
+export TAG
+export HOST_PORT
+export CONTAINER_PORT
+export GOCACHE
+export GOMODCACHE
+export GOLANGCI_LINT_CACHE
+
+ifeq ($(DOCKER_VARIANT),ubuntu)
+BUILDER_IMAGE ?= public.ecr.aws/docker/library/golang:1.26
+RUNTIME_IMAGE ?= public.ecr.aws/docker/library/ubuntu:26.04
+else
+BUILDER_IMAGE ?= golang:1.26-alpine
+RUNTIME_IMAGE ?= alpine:3.20
+endif
+
+.PHONY: worktree-info worktree-doctor worktree-compose-config clean-worktree bootstrap doctor dev dev-shell tidy lint test verify run build clean help docker-build docker-run docker-push
+
+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' "HTTP URL: http://127.0.0.1:$(HOST_PORT)"
+	@printf '%s\n' "Image ref: $(IMAGE_REF)"
+	@printf '%s\n' "Go cache: $(GOCACHE)"
+	@printf '%s\n' "Go module cache: $(GOMODCACHE)"
+	@printf '%s\n' "golangci-lint cache: $(GOLANGCI_LINT_CACHE)"
+
+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
+	@case "$(GOLANGCI_LINT_CACHE)" in "$(WORKTREE_ROOT)"/*) ;; *) printf '%s\n' "GOLANGCI_LINT_CACHE should stay inside this worktree: $(GOLANGCI_LINT_CACHE)"; exit 1;; esac
+	@if [ "$(HOST_PORT)" = "{{HTTP_PORT}}" ]; then printf '%s\n' "Warning: HOST_PORT uses the generated default {{HTTP_PORT}}; override it when another worktree is running."; fi
+	@if ! command -v lsof >/dev/null 2>&1; then printf '%s\n' "Port occupancy checks skipped: lsof is not available."; else \
+		if lsof -nP -iTCP:$(HOST_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_PORT $(HOST_PORT) is already in use." "Suggested override: HOST_PORT=$$(( $(HOST_PORT) + 10000 )) make dev"; fi; \
+	fi
+	@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
+
+dev:
+	GOPROXY=$(GOPROXY) GOSUMDB=$(GOSUMDB) $(COMPOSE) -f $(DEV_COMPOSE_FILE) up $(DEV_SERVICE)
+
+dev-shell:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) bash
+
+tidy:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go mod tidy
+
+lint:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) golangci-lint run --disable-all --enable=errcheck --enable=govet --enable=ineffassign --enable=staticcheck --enable=unused ./...
+
+test:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go test ./...
+
+verify: doctor lint test build
+
+run:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm --service-ports $(DEV_SERVICE)
+
+build:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go build -o bin/$(APP_NAME) ./cmd/server
+
+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 --platform $(DOCKER_PLATFORM) --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 -p $(HOST_PORT):$(CONTAINER_PORT) $(IMAGE_REF)
+
+docker-push:
+	docker push $(IMAGE_REF)

biucingcli/template_data/web-service/template/README.md

@@ -0,0 +1,164 @@
+# {{SERVICE_NAME}}
+
+This project was generated by BiucingCLI.
+
+## Stack
+
+- Go
+- Gin
+- Docker
+
+## Project Layout
+
+- `cmd/server`: application entrypoint
+- `internal/config`: config loading
+- `internal/handler`: HTTP handlers
+- `internal/service`: business logic
+- `internal/model`: response models
+- `internal/router`: route wiring
+- `internal/runtime`: bounded HTTP serving and graceful shutdown
+- `configs`: local config files
+- `tests`: integration-style HTTP tests
+
+## 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
+```
+
+The service reads configuration from `configs/config.yaml` by default.
+
+## Runtime Safety
+
+- `SIGINT` and `SIGTERM` stop accepting new connections and drain in-flight HTTP requests.
+- HTTP read, read-header, write, and idle timeouts are configured under `server` in `configs/config.yaml`.
+- Graceful shutdown is bounded by `server.shutdown_timeout_seconds`; after the deadline, open connections are force-closed and the process exits non-zero.
+- The runtime image checks `GET /healthz` every 10 seconds. Compose allows 15 seconds for the default 10-second shutdown window.
+
+## Environment
+
+- `Brewfile`: optional host workstation tool installation
+- `.mise.toml`: pinned Go version for host workflows
+- `Dockerfile.dev`: Go development image with `air` and `golangci-lint`
+- `compose.dev.yaml`: local Docker development workflow
+- `.air.toml`: hot reload config for the development container
+- `scripts/bootstrap`: host-oriented setup helper when you do not use Docker
+- `scripts/doctor`: local environment checks
+- `make lint`: baseline static analysis with `golangci-lint`
+- `make verify`: run doctor, lint, and tests together inside Docker
+- the development image prewarms `go mod download` so the first Docker-based dev shell and verification flow spend less time resolving modules
+- `GOPROXY` and `GOSUMDB` can be overridden on `make bootstrap`, `make dev`, and `make docker-build` when your network needs a different module proxy or checksum policy
+
+## Example Endpoints
+
+- `GET /healthz`: lightweight health check
+- `GET /api/v1/ping`: sample versioned API endpoint
+- `GET /api/v1/users`: list sample users from an in-memory repository
+- `GET /api/v1/users/:id`: fetch a sample user by ID
+
+## Docker
+
+Start the hot-reload development container:
+
+```bash
+make dev
+```
+
+Open a shell in the development container:
+
+```bash
+make dev-shell
+```
+
+Build the runtime image:
+
+```bash
+make docker-build
+```
+
+Build with the Ubuntu runtime path:
+
+```bash
+make docker-build DOCKER_VARIANT=ubuntu
+```
+
+Build and run the Ubuntu variant end to end:
+
+```bash
+make docker-build DOCKER_VARIANT=ubuntu IMAGE={{SERVICE_NAME}}-ubuntu TAG=dev
+make docker-run IMAGE={{SERVICE_NAME}}-ubuntu TAG=dev HOST_PORT={{HTTP_PORT}}
+```
+
+Run the container:
+
+```bash
+make docker-run
+```
+
+`make docker-run` starts whatever image tag you last built or specify explicitly through `IMAGE` and `TAG`.
+
+## Worktree Workflow
+
+This starter is safe to run from parallel Git worktrees when each worktree keeps its own identity and host port.
+
+```bash
+make worktree-info
+make worktree-doctor
+make worktree-compose-config
+HOST_PORT=8081 make dev
+HOST_PORT=8081 make docker-run
+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 `{{SERVICE_NAME}}-$(WORKTREE_ID)`, so Compose containers, networks, and volumes stay scoped to the worktree.
+- `IMAGE` defaults to the worktree slug and `TAG` defaults to `dev`, so runtime image tags do not overwrite another worktree by default.
+- `GOCACHE`, `GOMODCACHE`, and `GOLANGCI_LINT_CACHE` stay under the current worktree's `.cache/` directory.
+- The Docker dev workflow mounts Go build, module, and lint caches as Compose-scoped volumes, so dependency versions and downloads do not bleed across worktrees.
+- `make worktree-doctor` checks whether `HOST_PORT` is already in use and prints a suggested override.
+- `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.
+
+Push a tagged image:
+
+```bash
+make docker-push IMAGE=registry.example.com/{{SERVICE_NAME}} TAG=0.1.0
+```
+
+Run with Docker Compose:
+
+```bash
+docker compose up --build
+```
+
+The Docker defaults are:
+
+- `DOCKER_VARIANT=alpine`: `golang:1.26-alpine` + `alpine:3.20`
+- `DOCKER_VARIANT=ubuntu`: `public.ecr.aws/docker/library/golang:1.26` + `public.ecr.aws/docker/library/ubuntu:26.04`
+
+You can also override the exact images directly:
+
+```bash
+make docker-build BUILDER_IMAGE=public.ecr.aws/docker/library/golang:1.26 RUNTIME_IMAGE=public.ecr.aws/docker/library/ubuntu:26.04
+```