feat(sdk/go): add Go SDK foundation, types, and sandbox client (A)

sdk/go/Makefile

@@ -0,0 +1,45 @@
+MISE := $(shell command -v mise 2>/dev/null)
+
+.PHONY: test test-integration lint fmt build ci docs-check
+
+test:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run test
+
+test-integration:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run test:integration
+
+lint:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run lint
+
+fmt:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run fmt
+
+build:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run build
+
+ci:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run ci
+
+docs-check:
+ifndef MISE
+	$(error mise is not installed. Install from https://mise.jdx.dev)
+endif
+	mise run docs:check

sdk/go/go.mod

@@ -0,0 +1,22 @@
+module github.com/NVIDIA/OpenShell/sdk/go
+
+go 1.24.0
+
+toolchain go1.26.4
+
+require (
+	github.com/stretchr/testify v1.11.1
+	golang.org/x/oauth2 v0.35.0
+	google.golang.org/grpc v1.80.0
+	google.golang.org/protobuf v1.36.11
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.33.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

sdk/go/go.sum

@@ -0,0 +1,50 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=
+go.opentelemetry.io/otel v1.39.0/go.mod h1:kLlFTywNWrFyEdH0oj2xK0bFYZtHRYUdv1NklR/tgc8=
+go.opentelemetry.io/otel/metric v1.39.0 h1:d1UzonvEZriVfpNKEVmHXbdf909uGTOQjA0HF0Ls5Q0=
+go.opentelemetry.io/otel/metric v1.39.0/go.mod h1:jrZSWL33sD7bBxg1xjrqyDjnuzTUB0x1nBERXd7Ftcs=
+go.opentelemetry.io/otel/sdk v1.39.0 h1:nMLYcjVsvdui1B/4FRkwjzoRVsMK8uL/cj0OyhKzt18=
+go.opentelemetry.io/otel/sdk v1.39.0/go.mod h1:vDojkC4/jsTJsE+kh+LXYQlbL8CgrEcwmt1ENZszdJE=
+go.opentelemetry.io/otel/sdk/metric v1.39.0 h1:cXMVVFVgsIf2YL6QkRF4Urbr/aMInf+2WKg+sEJTtB8=
+go.opentelemetry.io/otel/sdk/metric v1.39.0/go.mod h1:xq9HEVH7qeX69/JnwEfp6fVq5wosJsY1mt4lLfYdVew=
+go.opentelemetry.io/otel/trace v1.39.0 h1:2d2vfpEDmCJ5zVYz7ijaJdOF59xLomrvj7bjt6/qCJI=
+go.opentelemetry.io/otel/trace v1.39.0/go.mod h1:88w4/PnZSazkGzz/w84VHpQafiU4EtqqlVdxWy+rNOA=
+golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
+golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
+golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516 h1:sNrWoksmOyF5bvJUcnmbeAmQi8baNhqg5IWaI3llQqU=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260120221211-b8f7ae30c516/go.mod h1:j9x/tPzZkyxcgEFkiKEEGxfvyumM01BEtsW8xzOahRQ=
+google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
+google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

sdk/go/mise.toml

@@ -0,0 +1,242 @@
+[tools]
+go = "1.25"
+protoc = "29.6"
+"go:github.com/golangci/golangci-lint/v2/cmd/golangci-lint" = "2.12"
+"go:google.golang.org/protobuf/cmd/protoc-gen-go" = "1.36.11"
+"go:google.golang.org/grpc/cmd/protoc-gen-go-grpc" = "1.6.2"
+
+[tasks.test]
+description = "Run unit tests with coverage"
+run = "go test -coverprofile=coverage.out -coverpkg=./openshell/... -race ./..."
+
+[tasks."test:integration"]
+description = "Run integration tests"
+run = "go test -tags=integration -race ./..."
+
+[tasks.lint]
+description = "Run linter"
+run = "golangci-lint run ./..."
+
+[tasks.fmt]
+description = "Format code"
+run = "goimports -w . && go fmt ./..."
+
+[tasks.build]
+description = "Build all packages"
+run = "go build ./..."
+
+[tasks.ci]
+description = "Run full CI pipeline"
+depends = ["lint", "build", "test", "proto:check", "docs:check"]
+
+[tasks."docs:check"]
+description = "Verify every public package has a docs page"
+run = """
+#!/usr/bin/env bash
+set -euo pipefail
+
+DOCS_DIR="docs/src/api"
+SUMMARY="docs/src/SUMMARY.md"
+MISSING=0
+
+# Find all public packages with a doc.go (excluding internal, proto, types)
+for docfile in openshell/v1/*/doc.go; do
+  pkg=$(basename "$(dirname "$docfile")")
+
+  # Skip internal packages and types (no user-facing docs needed)
+  case "$pkg" in
+    internal|types) continue ;;
+  esac
+
+  # Check for matching docs page
+  if [ ! -f "$DOCS_DIR/$pkg.md" ]; then
+    echo "MISSING: $DOCS_DIR/$pkg.md (package openshell/v1/$pkg has doc.go but no docs page)"
+    MISSING=$((MISSING + 1))
+  fi
+
+  # Check for SUMMARY.md entry
+  if ! grep -q "api/$pkg.md" "$SUMMARY" 2>/dev/null; then
+    echo "MISSING: SUMMARY.md entry for api/$pkg.md"
+    MISSING=$((MISSING + 1))
+  fi
+done
+
+if [ "$MISSING" -gt 0 ]; then
+  echo ""
+  echo "ERROR: $MISSING documentation gaps found."
+  echo "Every public package with doc.go needs a docs/src/api/<pkg>.md page"
+  echo "and a SUMMARY.md entry. See Constitution XIII."
+  exit 1
+fi
+
+echo "Docs check passed: all public packages have documentation."
+"""
+
+[tasks."proto:gen"]
+description = "Generate Go bindings from proto files"
+run = """
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Check required tools
+for tool in protoc protoc-gen-go protoc-gen-go-grpc; do
+  if ! command -v "$tool" &>/dev/null; then
+    echo "ERROR: $tool not found. Run 'mise install' to install it."
+    exit 1
+  fi
+done
+
+MODULE="github.com/NVIDIA/OpenShell/sdk/go"
+PROTO_DIR="proto"
+
+# Create output directories
+mkdir -p "$PROTO_DIR/openshellv1" "$PROTO_DIR/datamodelv1" "$PROTO_DIR/sandboxv1"
+
+# M flag mappings for Go package paths
+M_FLAGS=""
+M_FLAGS="$M_FLAGS --go_opt=Mopenshell.proto=$MODULE/proto/openshellv1"
+M_FLAGS="$M_FLAGS --go_opt=Mdatamodel.proto=$MODULE/proto/datamodelv1"
+M_FLAGS="$M_FLAGS --go_opt=Msandbox.proto=$MODULE/proto/sandboxv1"
+M_FLAGS="$M_FLAGS --go-grpc_opt=Mopenshell.proto=$MODULE/proto/openshellv1"
+M_FLAGS="$M_FLAGS --go-grpc_opt=Mdatamodel.proto=$MODULE/proto/datamodelv1"
+M_FLAGS="$M_FLAGS --go-grpc_opt=Msandbox.proto=$MODULE/proto/sandboxv1"
+
+# Generate Go code for all proto files
+# Use module= option to strip the module prefix from the output path,
+# so files land in proto/openshellv1/ etc. instead of the full module path
+protoc \
+  --proto_path="$PROTO_DIR" \
+  --go_out=. \
+  --go_opt=module=$MODULE \
+  --go-grpc_out=. \
+  --go-grpc_opt=module=$MODULE \
+  $M_FLAGS \
+  "$PROTO_DIR/openshell.proto" \
+  "$PROTO_DIR/datamodel.proto" \
+  "$PROTO_DIR/sandbox.proto"
+
+echo "Proto generation complete."
+echo "Generated packages:"
+for pkg in openshellv1 datamodelv1 sandboxv1; do
+  echo "  $PROTO_DIR/$pkg/: $(ls "$PROTO_DIR/$pkg/"*.go 2>/dev/null | wc -l | tr -d ' ') files"
+done
+"""
+
+[tasks."proto:check"]
+description = "Verify generated proto files are up to date"
+run = """
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Check required tools
+for tool in protoc protoc-gen-go protoc-gen-go-grpc; do
+  if ! command -v "$tool" &>/dev/null; then
+    echo "ERROR: $tool not found. Run 'mise install' to install it."
+    exit 1
+  fi
+done
+
+MODULE="github.com/NVIDIA/OpenShell/sdk/go"
+PROTO_DIR="proto"
+WORK_DIR=$(mktemp -d)
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+# Create output directories in temp
+mkdir -p "$WORK_DIR/proto/openshellv1" "$WORK_DIR/proto/datamodelv1" "$WORK_DIR/proto/sandboxv1"
+
+# M flag mappings (same as proto:gen)
+M_FLAGS=""
+M_FLAGS="$M_FLAGS --go_opt=Mopenshell.proto=$MODULE/proto/openshellv1"
+M_FLAGS="$M_FLAGS --go_opt=Mdatamodel.proto=$MODULE/proto/datamodelv1"
+M_FLAGS="$M_FLAGS --go_opt=Msandbox.proto=$MODULE/proto/sandboxv1"
+M_FLAGS="$M_FLAGS --go-grpc_opt=Mopenshell.proto=$MODULE/proto/openshellv1"
+M_FLAGS="$M_FLAGS --go-grpc_opt=Mdatamodel.proto=$MODULE/proto/datamodelv1"
+M_FLAGS="$M_FLAGS --go-grpc_opt=Msandbox.proto=$MODULE/proto/sandboxv1"
+
+# Generate to temp directory
+protoc \
+  --proto_path="$PROTO_DIR" \
+  --go_out="$WORK_DIR" \
+  --go_opt=module=$MODULE \
+  --go-grpc_out="$WORK_DIR" \
+  --go-grpc_opt=module=$MODULE \
+  $M_FLAGS \
+  "$PROTO_DIR/openshell.proto" \
+  "$PROTO_DIR/datamodel.proto" \
+  "$PROTO_DIR/sandbox.proto"
+
+# Diff against committed files
+DIFF_OUTPUT=$(diff -r "$WORK_DIR/proto" "$PROTO_DIR" \
+  --exclude="*.proto" \
+  --exclude="UPSTREAM_VERSION" \
+  2>&1) || true
+
+if [ -n "$DIFF_OUTPUT" ]; then
+  echo "ERROR: Generated proto files are out of date."
+  echo "Run 'mise run proto:gen' to regenerate."
+  echo ""
+  echo "$DIFF_OUTPUT"
+  exit 1
+fi
+
+echo "Proto check passed: generated files are up to date."
+"""
+
+[tasks."proto:clean"]
+description = "Remove all generated proto files"
+run = """
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROTO_DIR="proto"
+
+# Remove all generated .pb.go files
+find "$PROTO_DIR" -name "*.pb.go" -delete 2>/dev/null || true
+
+# Remove empty generated subdirectories
+for dir in "$PROTO_DIR"/*/; do
+  [ -d "$dir" ] && rmdir "$dir" 2>/dev/null || true
+done
+
+echo "Proto clean complete."
+"""
+
+[tasks."proto:sync"]
+description = "Sync proto files from upstream OpenShell repo"
+run = """
+#!/usr/bin/env bash
+set -euo pipefail
+
+UPSTREAM_PATH="${UPSTREAM_PATH:-../OpenShell/proto}"
+
+if [ ! -d "$UPSTREAM_PATH" ]; then
+  echo "ERROR: Upstream proto directory not found: $UPSTREAM_PATH"
+  echo "Set UPSTREAM_PATH env var to the correct location."
+  exit 1
+fi
+
+PROTO_DIR="proto"
+mkdir -p "$PROTO_DIR"
+
+PROTO_FILES="openshell.proto datamodel.proto sandbox.proto"
+for f in $PROTO_FILES; do
+  src="$UPSTREAM_PATH/$f"
+  if [ ! -f "$src" ]; then
+    echo "ERROR: Proto file not found: $src"
+    exit 1
+  fi
+  cp "$src" "$PROTO_DIR/$f"
+  echo "Copied $f"
+done
+
+# Record upstream commit SHA
+UPSTREAM_REPO_DIR="$(cd "$UPSTREAM_PATH/.." && pwd)"
+if [ -d "$UPSTREAM_REPO_DIR/.git" ]; then
+  SHA=$(git -C "$UPSTREAM_REPO_DIR" rev-parse HEAD)
+else
+  SHA="unknown"
+fi
+echo "$SHA" > "$PROTO_DIR/UPSTREAM_VERSION"
+echo "Upstream version: $SHA"
+echo "Proto sync complete."
+"""