Initial scaffolding: CLI, wait-for subcommand, retry, logging, safety, Helm chart, CI/CD, docs

- Go CLI with cobra: root command + wait-for subcommand
- wait-for: TCP/HTTP/HTTPS endpoint checking with retries, backoff, jitter
- internal/retry: configurable retry logic with exponential backoff
- internal/logging: structured text/JSON logging with secret redaction
- internal/safety: path traversal prevention for file writes
- Dockerfile: multi-arch scratch-based build, non-root UID 65534
- Helm chart: security-hardened initContainer injection templates
- GitHub Actions: CI (lint/test/build/helm-lint) and release workflows
- 28 unit tests across all packages
- Examples: nginx-waitfor, postgres-migrate-seed, config-render
- Docs: README with FAQ, usage guide, security threat model, design doc

Author: mikkeldamsgaard

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+      - uses: golangci/golangci-lint-action@v6
+        with:
+          version: latest
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+      - run: go test ./... -count=1 -timeout 60s -race -coverprofile=coverage.out
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.out
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+      - run: make build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: initium-binary
+          path: bin/initium
+
+  helm-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azure/setup-helm@v4
+      - run: helm lint charts/initium
+      - run: helm template test-release charts/initium --set sampleDeployment.enabled=true --set 'initContainers[0].name=wait' --set 'initContainers[0].command[0]=wait-for' --set 'initContainers[0].args[0]=--target' --set 'initContainers[0].args[1]=tcp://localhost:5432'
+

.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  packages: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+
+      - run: go test ./... -count=1 -timeout 60s -race
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            VERSION=${{ steps.version.outputs.VERSION }}
+          tags: |
+            ghcr.io/kitstream/initium:${{ steps.version.outputs.VERSION }}
+            ghcr.io/kitstream/initium:latest
+          sbom: true
+          provenance: true
+

.gitignore

@@ -0,0 +1,16 @@
+# IDE
+.idea/
+*.iml
+# Go
+bin/
+*.exe
+*.dll
+*.so
+*.dylib
+# Test
+*.test
+*.out
+coverage.out
+# OS
+.DS_Store
+Thumbs.db

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Project scaffolding with Go module, CLI framework (cobra), and repo layout
+- `wait-for` subcommand: wait for TCP and HTTP(S) endpoints with retries, exponential backoff, and jitter
+- `internal/retry` package with configurable retry logic, backoff, and jitter
+- `internal/logging` package with text and JSON structured logging, automatic secret redaction
+- `internal/safety` package with path traversal prevention for file writes
+- Dockerfile for multi-arch scratch-based builds (runs as non-root UID 65534)
+- Makefile with build, test, lint, and Docker targets
+- Helm chart skeleton with security-hardened initContainer templates
+- GitHub Actions CI workflow (lint, test, build) and release workflow (container build/push with SBOM)
+- Unit tests for retry logic, logging, safety path validation, and wait-for subcommand
+- Examples for nginx-waitfor, postgres-migrate-seed, and config-render use cases
+- Documentation: README, usage guide, security threat model, and architecture/design docs
+- SECURITY.md with vulnerability reporting instructions
+- Apache 2.0 LICENSE
+
+### Security
+- All file operations constrained to --workdir with path traversal prevention
+- Automatic redaction of sensitive keys (token, password, secret, etc.) in logs
+- Container runs as non-root with read-only root filesystem and all capabilities dropped
+

Dockerfile

@@ -0,0 +1,23 @@
+FROM --platform=$BUILDPLATFORM golang:1.25-alpine AS builder
+
+ARG TARGETOS TARGETARCH
+ARG VERSION=dev
+
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
+    -o /initium ./cmd/initium
+
+FROM scratch
+
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=builder /initium /initium
+
+USER 65534:65534
+
+ENTRYPOINT ["/initium"]
+

LICENSE

@@ -0,0 +1,20 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+Copyright 2025 Kitstream Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

Makefile

@@ -0,0 +1,32 @@
+BINARY   := initium
+MODULE   := github.com/kitstream/initium
+VERSION  ?= dev
+LDFLAGS  := -s -w -X main.version=$(VERSION)
+
+.PHONY: all build test lint clean
+
+all: lint test build
+
+build:
+	CGO_ENABLED=0 go build -trimpath -ldflags="$(LDFLAGS)" -o bin/$(BINARY) ./cmd/initium
+
+test:
+	go test ./... -count=1 -timeout 60s -race
+
+lint:
+	@command -v golangci-lint >/dev/null 2>&1 || { echo "golangci-lint not installed, skipping lint"; exit 0; }
+	golangci-lint run ./...
+
+clean:
+	rm -rf bin/
+
+docker-build:
+	docker buildx build --platform linux/amd64,linux/arm64 \
+		--build-arg VERSION=$(VERSION) \
+		-t ghcr.io/kitstream/initium:$(VERSION) .
+
+docker-push:
+	docker buildx build --platform linux/amd64,linux/arm64 \
+		--build-arg VERSION=$(VERSION) \
+		-t ghcr.io/kitstream/initium:$(VERSION) --push .
+