P0: Project scaffolding and foundations

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.go]
+indent_style = tab
+
+[*.{yml,yaml,json,md}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build-test:
+    # darwin/arm64-only project: build and test on Apple Silicon runners.
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Build
+        run: go build ./...
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test -race ./...
+
+  lint:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v7
+        with:
+          # v2.10.x is built with Go 1.25; v1.x cannot lint a go 1.25 module.
+          version: v2.10.1

.gitignore

@@ -1,7 +1,6 @@
 # Binaries
 /bin/
 /dist/
-macvz-kubelet
 *.exe
 *.test
 *.out

.golangci.yml

@@ -0,0 +1,8 @@
+version: "2"
+
+linters:
+  default: standard # errcheck, govet, ineffassign, staticcheck, unused
+
+formatters:
+  enable:
+    - gofmt

Makefile

@@ -0,0 +1,52 @@
+# macvz-kubelet build tooling
+
+BINARY      := macvz-kubelet
+PKG         := github.com/chimerakang/macvz
+CMD         := ./cmd/macvz-kubelet
+BIN_DIR     := bin
+
+VERSION     ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+COMMIT      ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo none)
+DATE        ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+
+VPKG        := $(PKG)/internal/version
+LDFLAGS     := -s -w \
+	-X $(VPKG).Version=$(VERSION) \
+	-X $(VPKG).Commit=$(COMMIT) \
+	-X $(VPKG).Date=$(DATE)
+
+.DEFAULT_GOAL := build
+
+.PHONY: build
+build: ## Build the binary into bin/ with version stamping
+	@mkdir -p $(BIN_DIR)
+	go build -ldflags "$(LDFLAGS)" -o $(BIN_DIR)/$(BINARY) $(CMD)
+
+.PHONY: test
+test: ## Run unit tests
+	go test ./...
+
+.PHONY: vet
+vet: ## Run go vet
+	go vet ./...
+
+.PHONY: lint
+lint: ## Run golangci-lint (must be installed)
+	golangci-lint run
+
+.PHONY: fmt
+fmt: ## Format all Go source
+	gofmt -s -w .
+
+.PHONY: tidy
+tidy: ## Tidy module dependencies
+	go mod tidy
+
+.PHONY: clean
+clean: ## Remove build artifacts
+	rm -rf $(BIN_DIR)
+
+.PHONY: help
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

cmd/macvz-kubelet/main.go

@@ -0,0 +1,60 @@
+// Command macvz-kubelet runs on each Apple Silicon Mac and registers it as a
+// Kubernetes node via Virtual Kubelet, launching Pods as native micro-VMs.
+//
+// P0 wires configuration, logging, and version reporting. Node registration and
+// the Pod lifecycle are implemented in P2.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/chimerakang/macvz/internal/version"
+	"github.com/chimerakang/macvz/pkg/config"
+	"k8s.io/klog/v2"
+)
+
+func main() {
+	var (
+		configPath  string
+		showVersion bool
+	)
+	flag.StringVar(&configPath, "config", "", "path to the YAML config file")
+	flag.BoolVar(&showVersion, "version", false, "print version and exit")
+
+	// Register klog's flags (e.g. -v, --logtostderr) on the default FlagSet.
+	klog.InitFlags(nil)
+	flag.Parse()
+
+	if showVersion {
+		fmt.Println(version.String())
+		return
+	}
+
+	if err := run(configPath); err != nil {
+		klog.ErrorS(err, "macvz-kubelet exited with error")
+		klog.Flush()
+		os.Exit(1)
+	}
+	klog.Flush()
+}
+
+func run(configPath string) error {
+	cfg, err := config.Load(configPath)
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+
+	klog.InfoS("starting macvz-kubelet",
+		"version", version.Version,
+		"node", cfg.NodeName,
+		"runtimeSocket", cfg.RuntimeSocket,
+		"logLevel", cfg.LogLevel,
+	)
+
+	// TODO(P2): build the runtime driver, construct the provider, and start the
+	// Virtual Kubelet node controller here.
+	klog.InfoS("node registration not yet implemented (lands in P2); exiting cleanly")
+	return nil
+}

config.example.yaml

@@ -0,0 +1,16 @@
+# Example macvz-kubelet configuration.
+# All fields are optional; omitted values fall back to built-in defaults.
+# Run with: macvz-kubelet --config ./config.yaml
+
+# Kubernetes node name this process registers as. Defaults to the OS hostname.
+nodeName: mac-mini-01
+
+# Path to the kubeconfig used to reach the API server.
+# Leave empty to use in-cluster config or the KUBECONFIG environment variable.
+kubeconfigPath: ""
+
+# Path to the apple/container service API socket.
+runtimeSocket: /var/run/com.apple.container.sock
+
+# Log verbosity: "info" or "debug" (klog -v levels also honored via flags).
+logLevel: info

go.mod

@@ -0,0 +1,52 @@
+module github.com/chimerakang/macvz
+
+go 1.25.0
+
+require (
+	github.com/virtual-kubelet/virtual-kubelet v1.12.0
+	gopkg.in/yaml.v3 v3.0.1
+	k8s.io/api v0.35.0
+	k8s.io/klog/v2 v2.130.1
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/emicklei/go-restful/v3 v3.12.2 // indirect
+	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/google/gnostic-models v0.7.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	go.yaml.in/yaml/v2 v2.4.3 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/net v0.47.0 // indirect
+	golang.org/x/oauth2 v0.32.0 // indirect
+	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/term v0.37.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
+	golang.org/x/time v0.14.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	k8s.io/apimachinery v0.35.0 // indirect
+	k8s.io/client-go v0.35.0 // indirect
+	k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 // indirect
+	k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 // indirect
+	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
+	sigs.k8s.io/randfill v1.0.0 // indirect
+	sigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect
+	sigs.k8s.io/yaml v1.6.0 // indirect
+)