initial scaffold: envstruct project structure

Author: mtingers

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ['1.23', '1.24']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+      - run: go test ./... -count=1 -race
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - uses: golangci/golangci-lint-action@v6
+        with:
+          version: latest

.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ['1.23', '1.24']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+      - name: Test
+        run: go test ./... -race -count=1
+      - name: Vet
+        run: go vet ./...
+
+  index:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Request pkg.go.dev indexing
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          curl -s "https://proxy.golang.org/github.com/agentine/envstruct/@v/${VERSION}.info" || true
+          curl -s "https://sum.golang.org/lookup/github.com/agentine/envstruct@${VERSION}" || true
+          echo "Requested indexing for github.com/agentine/envstruct@${VERSION}"

.gitignore

@@ -0,0 +1,27 @@
+# Binaries
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary
+*.test
+
+# Output
+*.out
+
+# Coverage
+coverage.txt
+coverage.html
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

Makefile

@@ -0,0 +1,23 @@
+.PHONY: install build test lint fmt clean ci
+
+install:
+	go mod tidy
+
+build:
+	go build ./...
+
+test:
+	go test -race -count=1 ./...
+
+lint:
+	go vet ./...
+	golangci-lint run
+
+fmt:
+	gofmt -w .
+
+clean:
+	go clean
+	rm -rf bin/
+
+ci: lint test

PLAN.md

@@ -0,0 +1,88 @@
+# envstruct
+
+**Replacement for:** [kelseyhightower/envconfig](https://github.com/kelseyhightower/envconfig)
+**Language:** Go
+**Package:** `github.com/agentine/envstruct`
+
+## Why
+
+kelseyhightower/envconfig has 8,524 importers and 20.2K GitHub dependents but has been dormant since May 2019 (last release v1.4.0). The sole maintainer is no longer active in OSS. There are 27 open issues and 31 open PRs with zero maintainer engagement. Existing alternatives (caarlos0/env, sethvargo/go-envconfig) have not captured envconfig's market share.
+
+## Scope
+
+A Go library that populates struct fields from environment variables using struct tags. Drop-in replacement for envconfig with modern Go practices.
+
+## Core Features
+
+1. **Struct tag parsing** — `env:"VAR_NAME"` tags to map env vars to struct fields
+2. **Type support** — string, int (all sizes), uint, float, bool, time.Duration, url.URL, custom types
+3. **Prefix support** — scoped env var lookup via configurable prefix (e.g., `APP_`)
+4. **Nested structs** — flatten or use delimiter-separated names (e.g., `APP_DB_HOST`)
+5. **Required fields** — `env:"VAR_NAME,required"` tag option
+6. **Default values** — `env:"VAR_NAME" default:"value"` tag
+7. **Custom decoders** — `Decoder` interface for user-defined types
+8. **Slice/map support** — comma-separated values for slices, key=value pairs for maps
+9. **Usage generation** — auto-generate usage text from struct tags
+10. **Error reporting** — clear error messages with field name, expected type, and env var name
+
+## Architecture
+
+```
+envstruct/
+├── envstruct.go        # Core Process/MustProcess functions
+├── decoder.go          # Type decoders and Decoder interface
+├── tags.go             # Struct tag parsing
+├── usage.go            # Usage text generation
+├── errors.go           # Typed error types
+├── envstruct_test.go   # Core tests
+├── decoder_test.go     # Decoder tests
+├── usage_test.go       # Usage tests
+├── example_test.go     # Runnable examples
+├── go.mod
+├── go.sum
+└── README.md
+```
+
+## API Surface
+
+```go
+// Process populates a struct from environment variables.
+func Process(prefix string, spec interface{}) error
+
+// MustProcess is like Process but panics on error.
+func MustProcess(prefix string, spec interface{})
+
+// Usage writes a usage message to the given writer.
+func Usage(prefix string, spec interface{}, out io.Writer) error
+
+// Decoder is implemented by types that can decode themselves from a string.
+type Decoder interface {
+    Decode(value string) error
+}
+
+// Setter is implemented by types that can set themselves from a string (envconfig compat).
+type Setter interface {
+    Set(value string) error
+}
+```
+
+## Migration Path
+
+- Same `Process(prefix, &spec)` function signature as envconfig
+- Supports envconfig's struct tag format for easy migration
+- Also supports `env:"NAME"` tag format (more conventional)
+- Decoder interface is compatible with envconfig's interface
+
+## Deliverables
+
+1. Core library with full type support
+2. Comprehensive test suite (>90% coverage)
+3. README with migration guide from envconfig
+4. Runnable examples
+5. CI configuration (GitHub Actions)
+
+## Non-Goals
+
+- File-based config (.env, YAML, TOML) — use dedicated libraries
+- Config hot-reloading — environment variables are read once at startup
+- CLI flag parsing — separate concern

README.md

@@ -0,0 +1,13 @@
+# envstruct
+
+A Go library that populates struct fields from environment variables. Drop-in replacement for [kelseyhightower/envconfig](https://github.com/kelseyhightower/envconfig).
+
+## Install
+
+```
+go get github.com/agentine/envstruct
+```
+
+## License
+
+MIT

decoder.go

@@ -0,0 +1,12 @@
+package envstruct
+
+// Decoder is implemented by types that can decode themselves from a string.
+type Decoder interface {
+	Decode(value string) error
+}
+
+// Setter is implemented by types that can set themselves from a string.
+// This interface exists for compatibility with kelseyhightower/envconfig.
+type Setter interface {
+	Set(value string) error
+}

decoder_test.go

@@ -0,0 +1,17 @@
+package envstruct
+
+import "testing"
+
+func TestDecoderInterface(t *testing.T) {
+	// Verify Decoder and Setter interfaces are defined.
+	var _ Decoder = (*testDecoder)(nil)
+	var _ Setter = (*testSetter)(nil)
+}
+
+type testDecoder struct{ val string }
+
+func (d *testDecoder) Decode(value string) error { d.val = value; return nil }
+
+type testSetter struct{ val string }
+
+func (s *testSetter) Set(value string) error { s.val = value; return nil }

envstruct.go

@@ -0,0 +1,27 @@
+// Package envstruct populates struct fields from environment variables.
+//
+// It is a drop-in replacement for kelseyhightower/envconfig with the same
+// Process(prefix, &spec) function signature.
+package envstruct
+
+import "io"
+
+// Process populates the struct pointed to by spec with values from
+// environment variables. The prefix is prepended to each field name
+// (or tag override) when looking up environment variables.
+func Process(prefix string, spec interface{}) error {
+	return nil
+}
+
+// MustProcess is like Process but panics on error.
+func MustProcess(prefix string, spec interface{}) {
+	if err := Process(prefix, spec); err != nil {
+		panic(err)
+	}
+}
+
+// Usage writes a usage message describing the environment variables
+// expected by spec to the given writer.
+func Usage(prefix string, spec interface{}, out io.Writer) error {
+	return nil
+}