biucingcli 0.9.1__py3-none-any.whl

biucingcli/template_data/harmonyos/template.json

@@ -0,0 +1,134 @@
+{
+  "name": "harmonyos",
+  "description": "ArkTS HarmonyOS app starter for DevEco Studio projects",
+  "category": "native",
+  "stack": ["ArkTS", "ArkUI", "HarmonyOS", "DevEco Studio", "hvigor", "ohpm"],
+  "tags": ["harmonyos", "arkts", "arkui", "deveco", "native"],
+  "platforms": ["harmonyos"],
+  "maturity": {
+    "level": "experimental",
+    "summary": "HarmonyOS starter with DevEco-compatible project files, ArkTS entry ability, doctor checks, Hypium test wiring, build verification, artifact checks, and local release-signing preflight."
+  },
+  "validation": {
+    "status": "generated-project-verified",
+    "verification_tier": "generated-project",
+    "evidence": [
+      "python unittest template rendering coverage",
+      "repo-level template metadata and placeholder validation",
+      "generated-project bootstrap, lint, test, build, artifact, and release-preflight commands"
+    ]
+  },
+  "operating_assumptions": [
+    "The starter assumes DevEco Studio or a local HarmonyOS SDK provides ohpm and hvigor.",
+    "Generated projects are structured for an ArkTS Stage model app with one entry module."
+  ],
+  "workflow_labels": ["bootstrap", "doctor", "lint", "test", "build", "verify", "release", "open"],
+  "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": [
+      "caches",
+      "generated-output",
+      "local-config",
+      "installed-app-identity",
+      "cleanup",
+      "diagnostics"
+    ],
+    "diagnostics": [
+      "make worktree-info",
+      "make worktree-doctor"
+    ],
+    "cleanup": [
+      "make clean-worktree"
+    ]
+  },
+  "variables": [
+    {
+      "name": "project_name",
+      "required": true,
+      "validator": "project-name"
+    },
+    {
+      "name": "display_name",
+      "required": false,
+      "default_from": "project_name",
+      "validator": "display-name"
+    },
+    {
+      "name": "bundle_name",
+      "required": true,
+      "prompt": "HarmonyOS bundle name: ",
+      "validator": "java-package"
+    },
+    {
+      "name": "harmony_module_name",
+      "required": false,
+      "default": "entry",
+      "validator": "identifier"
+    },
+    {
+      "name": "ability_name",
+      "required": false,
+      "default": "EntryAbility",
+      "validator": "identifier"
+    },
+    {
+      "name": "compatible_sdk_version",
+      "required": false,
+      "default": "5.0.0(12)",
+      "validator": "harmony-sdk-version"
+    },
+    {
+      "name": "target_sdk_version",
+      "required": false,
+      "default": "5.0.0(12)",
+      "validator": "harmony-sdk-version"
+    },
+    {
+      "name": "min_api_version",
+      "required": false,
+      "default": "12",
+      "validator": "positive-integer",
+      "maximum": 100
+    },
+    {
+      "name": "harmony_version_code",
+      "required": false,
+      "default": "1",
+      "validator": "positive-integer",
+      "maximum": 2100000000
+    },
+    {
+      "name": "harmony_version_name",
+      "required": false,
+      "default": "1.0.0",
+      "validator": "semantic-version"
+    },
+    {
+      "name": "organization_name",
+      "required": false,
+      "default": "Example Team",
+      "validator": "display-name"
+    }
+  ],
+  "next_steps": [
+    "make bootstrap",
+    "make doctor",
+    "make lint",
+    "make test",
+    "make build",
+    "make artifact-info",
+    "make verify",
+    "make release-preflight",
+    "open -a \"DevEco Studio\" ."
+  ]
+}

biucingcli/template_data/microservice/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", "proto"]
+
+[log]
+time = true

biucingcli/template_data/microservice/template/.dockerignore

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

biucingcli/template_data/microservice/template/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+.cache/
+bin/
+.env.local

biucingcli/template_data/microservice/template/.mise.toml

@@ -0,0 +1,3 @@
+[tools]
+go = "1.26.0"
+buf = "1.57.0"

biucingcli/template_data/microservice/template/Brewfile

@@ -0,0 +1,7 @@
+brew "buf"
+brew "docker"
+brew "go"
+brew "golangci-lint"
+brew "grpcurl"
+brew "jq"
+brew "mise"

biucingcli/template_data/microservice/template/Dockerfile

@@ -0,0 +1,44 @@
+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
+COPY deploy/otel-collector.yaml /app/deploy/otel-collector.yaml
+
+EXPOSE {{HTTP_PORT}}
+EXPOSE {{GRPC_PORT}}
+
+ENV CONFIG_FILE=/app/configs/config.yaml
+ENV OTEL_EXPORTER_OTLP_ENDPOINT={{OTEL_EXPORTER_ENDPOINT}}
+
+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/microservice/template/Dockerfile.dev

@@ -0,0 +1,50 @@
+FROM golang:1.26-bookworm
+
+WORKDIR /workspace
+
+ARG AIR_VERSION=1.65.3
+ARG BUF_VERSION=1.70.0
+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 unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+      arm64) air_arch="arm64"; buf_arch="aarch64"; golangci_arch="arm64" ;; \
+      amd64) air_arch="amd64"; buf_arch="x86_64"; 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/bufbuild/buf/releases/download/v${BUF_VERSION}/buf-Linux-${buf_arch}.tar.gz" \
+      | tar -xz -C /tmp; \
+    mv /tmp/buf/bin/buf /usr/local/bin/buf; \
+    rm -rf /tmp/buf; \
+    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/microservice/template/Makefile

@@ -0,0 +1,145 @@
+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
+HTTP_PORT ?={{HTTP_PORT}}
+GRPC_PORT ?={{GRPC_PORT}}
+HOST_HTTP_PORT ?={{HTTP_PORT}}
+HOST_GRPC_PORT ?={{GRPC_PORT}}
+HOST_DEPENDENCY_STORE_PORT ?={{DEPENDENCY_STORE_PORT}}
+HOST_OTEL_GRPC_PORT ?=4317
+HOST_OTEL_HTTP_PORT ?=4318
+DEV_COMPOSE_FILE ?=compose.dev.yaml
+DEV_SERVICE ?=app-dev
+DOCKER_VARIANT ?=alpine
+DOCKER_PLATFORM ?=linux/arm64
+COMPOSE_FILE ?=deploy/compose.yaml
+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 HTTP_PORT
+export GRPC_PORT
+export HOST_HTTP_PORT
+export HOST_GRPC_PORT
+export HOST_DEPENDENCY_STORE_PORT
+export HOST_OTEL_GRPC_PORT
+export HOST_OTEL_HTTP_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 proto lint test verify run up down logs 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' "HTTP URL: http://127.0.0.1:$(HOST_HTTP_PORT)"
+	@printf '%s\n' "gRPC host port: $(HOST_GRPC_PORT)"
+	@printf '%s\n' "{{DEPENDENCY_STORE}} host port: $(HOST_DEPENDENCY_STORE_PORT)"
+	@printf '%s\n' "OTel gRPC host port: $(HOST_OTEL_GRPC_PORT)"
+	@printf '%s\n' "OTel HTTP host port: $(HOST_OTEL_HTTP_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_HTTP_PORT)" = "{{HTTP_PORT}}" ]; then printf '%s\n' "Warning: HOST_HTTP_PORT uses the generated default {{HTTP_PORT}}; override it when another worktree is running."; fi
+	@if [ "$(HOST_GRPC_PORT)" = "{{GRPC_PORT}}" ]; then printf '%s\n' "Warning: HOST_GRPC_PORT uses the generated default {{GRPC_PORT}}; override it when another worktree is running."; fi
+	@if [ "$(HOST_DEPENDENCY_STORE_PORT)" = "{{DEPENDENCY_STORE_PORT}}" ]; then printf '%s\n' "Warning: HOST_DEPENDENCY_STORE_PORT uses {{DEPENDENCY_STORE_PORT}}; override it when another dependency store is running."; fi
+	@if [ "$(HOST_OTEL_GRPC_PORT)" = "4317" ]; then printf '%s\n' "Warning: HOST_OTEL_GRPC_PORT uses 4317; override it when another collector is running."; fi
+	@if [ "$(HOST_OTEL_HTTP_PORT)" = "4318" ]; then printf '%s\n' "Warning: HOST_OTEL_HTTP_PORT uses 4318; override it when another collector 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_HTTP_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_HTTP_PORT $(HOST_HTTP_PORT) is already in use." "Suggested override: HOST_HTTP_PORT=$$(( $(HOST_HTTP_PORT) + 10000 )) make dev"; fi; \
+		if lsof -nP -iTCP:$(HOST_GRPC_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_GRPC_PORT $(HOST_GRPC_PORT) is already in use." "Suggested override: HOST_GRPC_PORT=$$(( $(HOST_GRPC_PORT) + 10000 )) make dev"; fi; \
+		if lsof -nP -iTCP:$(HOST_DEPENDENCY_STORE_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_DEPENDENCY_STORE_PORT $(HOST_DEPENDENCY_STORE_PORT) is already in use." "Suggested override: HOST_DEPENDENCY_STORE_PORT=$$(( $(HOST_DEPENDENCY_STORE_PORT) + 10000 )) make dev"; fi; \
+		if lsof -nP -iTCP:$(HOST_OTEL_GRPC_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_OTEL_GRPC_PORT $(HOST_OTEL_GRPC_PORT) is already in use." "Suggested override: HOST_OTEL_GRPC_PORT=$$(( $(HOST_OTEL_GRPC_PORT) + 10000 )) make dev"; fi; \
+		if lsof -nP -iTCP:$(HOST_OTEL_HTTP_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_OTEL_HTTP_PORT $(HOST_OTEL_HTTP_PORT) is already in use." "Suggested override: HOST_OTEL_HTTP_PORT=$$(( $(HOST_OTEL_HTTP_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: proto
+	GOPROXY=$(GOPROXY) GOSUMDB=$(GOSUMDB) $(COMPOSE) -f $(DEV_COMPOSE_FILE) up $(DEV_SERVICE) {{DEPENDENCY_STORE}} otel-collector
+
+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
+
+proto:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) bash -lc "cd api && buf generate"
+
+lint: proto
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) bash -lc "cd api && buf lint && cd .. && golangci-lint run --disable-all --enable=errcheck --enable=govet --enable=ineffassign --enable=staticcheck --enable=unused ./..."
+
+test: proto
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) go test ./...
+
+verify: doctor lint test build
+
+run: proto
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm --service-ports $(DEV_SERVICE)
+
+up: proto
+	GOPROXY=$(GOPROXY) GOSUMDB=$(GOSUMDB) $(COMPOSE) -f $(DEV_COMPOSE_FILE) up $(DEV_SERVICE) {{DEPENDENCY_STORE}} otel-collector
+
+down:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) down --remove-orphans
+
+logs:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) logs -f
+
+build: proto
+	$(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: proto
+	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_HTTP_PORT):$(HTTP_PORT) -p $(HOST_GRPC_PORT):$(GRPC_PORT) $(IMAGE_REF)

biucingcli/template_data/microservice/template/README.md

@@ -0,0 +1,191 @@
+# {{SERVICE_NAME}}
+
+This project was generated by BiucingCLI.
+
+## Stack
+
+- Go
+- Gin
+- Protobuf
+- Buf
+- Docker Compose
+- OpenTelemetry
+- Docker
+
+## Project Layout
+
+- `cmd/server`: application startup and server wiring
+- `internal/config`: config loading and overrides
+- `internal/handler`: HTTP handlers
+- `internal/service`: business logic
+- `internal/transport`: gRPC server wiring
+- `internal/runtime`: coordinated HTTP/gRPC serving and bounded shutdown
+- `internal/telemetry`: OpenTelemetry setup
+- `api/proto`: protobuf contracts
+- `deploy`: local compose and collector config
+
+## Docker Workflow
+
+```bash
+make bootstrap
+make dev
+```
+
+Use `make up` when you want the service, `{{DEPENDENCY_STORE}}`, and the OpenTelemetry Collector to start together with hot reload inside Docker.
+
+## Available Commands
+
+```bash
+make bootstrap
+make dev
+make dev-shell
+make doctor
+make proto
+make lint
+make test
+make verify
+make build
+make docker-build
+make docker-run
+make clean
+make help
+```
+
+## Environment
+
+- `Brewfile`: optional host workstation tool installation
+- `.mise.toml`: pinned Go and Buf versions for host workflows
+- `Dockerfile.dev`: Go development image with `air`, `buf`, and `golangci-lint`
+- `compose.dev.yaml`: Docker development topology with the service, `{{DEPENDENCY_STORE}}`, and the collector
+- `.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 proto`: generate protobuf code through `Buf` inside Docker
+- `make test`: generate protobuf code, then run HTTP and in-memory gRPC contract tests inside Docker
+- `make verify`: run doctor, protobuf generation, lint, and tests together inside Docker
+- the development image prewarms `go mod download`; the first `make proto` may still fetch remote Buf plugin artifacts when the cache is empty
+- `GOPROXY` and `GOSUMDB` can be overridden on `make bootstrap`, `make dev`, `make up`, and `make docker-build` when your network needs a different Go module proxy or checksum policy
+
+## Runtime Defaults
+
+- HTTP port: `{{HTTP_PORT}}`
+- gRPC port: `{{GRPC_PORT}}`
+- Proto package: `{{PROTO_PACKAGE}}`
+- Local dependency store: `{{DEPENDENCY_STORE}}`
+- OTLP endpoint: `{{OTEL_EXPORTER_ENDPOINT}}`
+- HTTP read timeout: `5s`
+- HTTP read-header timeout: `5s`
+- HTTP write timeout: `15s`
+- HTTP idle timeout: `60s`
+- Graceful shutdown timeout: `10s`
+
+## Runtime Safety
+
+- `SIGINT` and `SIGTERM` start one coordinated shutdown for HTTP, gRPC, and OpenTelemetry.
+- The gRPC health service switches to `NOT_SERVING` before draining active RPCs.
+- HTTP stops accepting new work and drains in-flight requests with the configured deadline.
+- If gRPC graceful stop exceeds `server.shutdown_timeout_seconds`, the server is force-stopped 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.
+
+## Local Workflows
+
+Start the Docker development topology:
+
+```bash
+make dev
+```
+
+Open a shell in the development container:
+
+```bash
+make dev-shell
+```
+
+Run the composed local topology:
+
+```bash
+make up
+```
+
+Stop the composed topology:
+
+```bash
+make down
+```
+
+Tail compose logs:
+
+```bash
+make logs
+```
+
+Build the runtime image:
+
+```bash
+make docker-build
+```
+
+Run the runtime image directly:
+
+```bash
+make docker-run
+```
+
+## Worktree Workflow
+
+This starter is safe to run from parallel Git worktrees when each worktree keeps its own identity and host ports.
+
+```bash
+make worktree-info
+make worktree-doctor
+make worktree-compose-config
+HOST_HTTP_PORT=8081 HOST_GRPC_PORT=9091 HOST_DEPENDENCY_STORE_PORT=5433 make up
+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, dependency stores, and cache 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.
+- `HOST_HTTP_PORT`, `HOST_GRPC_PORT`, `HOST_DEPENDENCY_STORE_PORT`, `HOST_OTEL_GRPC_PORT`, and `HOST_OTEL_HTTP_PORT` can be overridden when several worktrees run at once.
+- `make worktree-doctor` checks whether published host ports are already in use and prints suggested overrides.
+- `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.
+
+## Contracts
+
+The canonical service contract lives under `api/proto/service/v1/service.proto`.
+Because the template accepts a caller-defined protobuf package while keeping a stable starter file layout, Buf exempts only `PACKAGE_DIRECTORY_MATCH`; every other `STANDARD` lint rule remains enabled.
+
+Generate Go code with:
+
+```bash
+make proto
+```
+
+The generated server registers `{{PROTO_PACKAGE}}.{{SERVICE_TYPE_NAME}}Service/Ping` on the configured gRPC port. The test suite calls the generated Go client over an in-memory gRPC listener and verifies the full method name plus the `message` and `service` response fields.
+
+With the service running, exercise the same contract from the command line:
+
+```bash
+grpcurl -plaintext \
+  -d '{"requestId":"local-check"}' \
+  127.0.0.1:{{GRPC_PORT}} \
+  {{PROTO_PACKAGE}}.{{SERVICE_TYPE_NAME}}Service/Ping
+```
+
+## Observability
+
+The template includes a local `OpenTelemetry Collector` config at `deploy/otel-collector.yaml`.
+
+When you run `make up` or `make dev`, the service exports telemetry to the collector container. When you run `make docker-run`, the service uses the endpoint from `configs/config.yaml` unless overridden by `OTEL_EXPORTER_OTLP_ENDPOINT`.
+
+## Source of Truth
+
+- `api/proto/*.proto`: RPC and message contracts
+- `api/buf.yaml` and `api/buf.gen.yaml`: protobuf workflow
+- `configs/config.yaml`: local service defaults
+- `deploy/compose.yaml`: local composed development
+- `Makefile`: supported team commands

biucingcli/template_data/microservice/template/api/buf.gen.yaml

@@ -0,0 +1,11 @@
+version: v2
+clean: true
+plugins:
+  - remote: buf.build/protocolbuffers/go
+    out: gen/go
+    opt:
+      - paths=source_relative
+  - remote: buf.build/grpc/go
+    out: gen/go
+    opt:
+      - paths=source_relative

biucingcli/template_data/microservice/template/api/buf.yaml

@@ -0,0 +1,11 @@
+version: v2
+modules:
+  - path: proto
+lint:
+  use:
+    - STANDARD
+  except:
+    - PACKAGE_DIRECTORY_MATCH
+breaking:
+  use:
+    - FILE

biucingcli/template_data/microservice/template/api/proto/service/v1/service.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package {{PROTO_PACKAGE}};
+
+option go_package = "{{MODULE_NAME}}/api/gen/go/service/v1;servicev1";
+
+service {{SERVICE_TYPE_NAME}}Service {
+  rpc Ping(PingRequest) returns (PingResponse);
+}
+
+message PingRequest {
+  string request_id = 1;
+}
+
+message PingResponse {
+  string message = 1;
+  string service = 2;
+}