up

src/Sdk/StellaOps.Sdk.Generator/go/README.md

@@ -0,0 +1,35 @@
+# Go SDK (SDKGEN-63-003)
+
+Deterministic generator settings for the Go SDK with context-first API design.
+
+## Prereqs
+- `STELLA_OAS_FILE` pointing to the frozen OpenAPI spec.
+- OpenAPI Generator CLI 7.4.0 jar at `tools/openapi-generator-cli-7.4.0.jar` (override with `STELLA_OPENAPI_GENERATOR_JAR`).
+- JDK 21 available on PATH (vendored at `../tools/jdk-21.0.1+12`; set `JAVA_HOME` if needed).
+
+## Generate
+```bash
+cd src/Sdk/StellaOps.Sdk.Generator
+STELLA_OAS_FILE=ts/fixtures/ping.yaml \
+STELLA_SDK_OUT=$(mktemp -d) \
+go/generate-go.sh
+```
+
+Outputs land in `out/go/` and are post-processed to normalize whitespace, inject the banner, and copy shared helpers (`hooks.go`).
+Override `STELLA_SDK_OUT` to keep the repo clean during local runs.
+
+## Design Principles
+
+- **Context-first**: All API methods accept `context.Context` as the first parameter for cancellation and deadline propagation.
+- **Interfaces**: Generated interfaces allow easy mocking in tests.
+- **RoundTripper hooks**: Auth, retry, and telemetry are implemented as composable `http.RoundTripper` wrappers via `hooks.go`.
+- **Deterministic**: Generation is reproducible given the same spec and toolchain lock.
+
+## Helpers
+
+The post-process step copies `hooks.go` into the output directory providing:
+- `AuthRoundTripper`: Injects Authorization header from token provider
+- `RetryRoundTripper`: Retries transient errors with exponential backoff
+- `TelemetryRoundTripper`: Adds client/trace headers
+- `WithClientHooks`: Composes round-trippers onto an `*http.Client`
+- `Paginate[T]`: Generic cursor-based pagination helper

src/Sdk/StellaOps.Sdk.Generator/go/config.yaml

@@ -0,0 +1,24 @@
+# OpenAPI Generator config for the StellaOps Go SDK (alpha)
+generatorName: go
+outputDir: out/go
+additionalProperties:
+  packageName: stellaops
+  packageVersion: "0.0.0-alpha"
+  isGoSubmodule: false
+  hideGenerationTimestamp: true
+  structPrefix: true
+  enumClassPrefix: true
+  generateInterfaces: true
+  useOneOfDiscriminatorLookup: true
+  withGoMod: true
+  goModuleName: "github.com/stella-ops/sdk-go"
+  gitUserId: "stella-ops"
+  gitRepoId: "sdk-go"
+
+# Post-process hook is supplied via env (STELLA_SDK_POSTPROCESS / postProcessFile)
+
+globalProperty:
+  apiDocs: false
+  modelDocs: false
+  apiTests: false
+  modelTests: false

src/Sdk/StellaOps.Sdk.Generator/go/generate-go.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(cd -- "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+config="$root_dir/go/config.yaml"
+spec="${STELLA_OAS_FILE:-}"
+
+if [ -z "$spec" ]; then
+  echo "STELLA_OAS_FILE is required (path to OpenAPI spec)" >&2
+  exit 1
+fi
+
+output_dir="${STELLA_SDK_OUT:-$root_dir/out/go}"
+mkdir -p "$output_dir"
+
+# Ensure postprocess copies shared helpers into the generated tree
+export STELLA_POSTPROCESS_ROOT="$output_dir"
+export STELLA_POSTPROCESS_LANG="go"
+
+JAR="${STELLA_OPENAPI_GENERATOR_JAR:-$root_dir/tools/openapi-generator-cli-7.4.0.jar}"
+if [ ! -f "$JAR" ]; then
+  echo "OpenAPI Generator CLI jar not found at $JAR" >&2
+  echo "Set STELLA_OPENAPI_GENERATOR_JAR or download to tools/." >&2
+  exit 1
+fi
+
+JAVA_OPTS="${JAVA_OPTS:-} -Dorg.openapitools.codegen.utils.postProcessFile=$root_dir/postprocess/postprocess.sh"
+export JAVA_OPTS
+
+java -jar "$JAR" generate \
+  -i "$spec" \
+  -g go \
+  -c "$config" \
+  --skip-validate-spec \
+  --enable-post-process-file \
+  --global-property models,apis,supportingFiles \
+  -o "$output_dir"
+
+# Ensure shared helpers are present even if upstream post-process hooks were skipped for some files
+if [ -d "$output_dir" ]; then
+  "$root_dir/postprocess/postprocess.sh" "$output_dir/client.go" 2>/dev/null || true
+fi
+
+echo "Go SDK generated at $output_dir"

src/Sdk/StellaOps.Sdk.Generator/go/test_generate_go.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(cd -- "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+script="$root_dir/go/generate-go.sh"
+spec="$root_dir/ts/fixtures/ping.yaml"
+jar_default="$root_dir/tools/openapi-generator-cli-7.4.0.jar"
+jar="${STELLA_OPENAPI_GENERATOR_JAR:-$jar_default}"
+
+if [ ! -f "$jar" ]; then
+  echo "SKIP: generator jar not found at $jar" >&2
+  exit 0
+fi
+
+if ! command -v java >/dev/null 2>&1; then
+  echo "SKIP: java not on PATH; set JAVA_HOME to run this smoke." >&2
+  exit 0
+fi
+
+out_dir="$(mktemp -d)"
+trap 'rm -rf "$out_dir"' EXIT
+
+STELLA_OAS_FILE="$spec" \
+STELLA_SDK_OUT="$out_dir" \
+STELLA_OPENAPI_GENERATOR_JAR="$jar" \
+"$script"
+
+# Check that client.go and go.mod were generated
+test -f "$out_dir/client.go" || { echo "missing generated client.go" >&2; exit 1; }
+test -f "$out_dir/go.mod" || { echo "missing generated go.mod" >&2; exit 1; }
+test -f "$out_dir/hooks.go" || { echo "missing hooks.go helper copy" >&2; exit 1; }
+
+echo "Go generator smoke test passed"

src/Sdk/StellaOps.Sdk.Generator/java/README.md

@@ -0,0 +1,45 @@
+# Java SDK (SDKGEN-63-004)
+
+Deterministic generator settings for the Java SDK with OkHttp client and builder pattern.
+
+## Prereqs
+- `STELLA_OAS_FILE` pointing to the frozen OpenAPI spec.
+- OpenAPI Generator CLI 7.4.0 jar at `tools/openapi-generator-cli-7.4.0.jar` (override with `STELLA_OPENAPI_GENERATOR_JAR`).
+- JDK 21 available on PATH (vendored at `../tools/jdk-21.0.1+12`; set `JAVA_HOME` if needed).
+
+## Generate
+```bash
+cd src/Sdk/StellaOps.Sdk.Generator
+STELLA_OAS_FILE=ts/fixtures/ping.yaml \
+STELLA_SDK_OUT=$(mktemp -d) \
+java/generate-java.sh
+```
+
+Outputs land in `out/java/` and are post-processed to normalize whitespace, inject the banner, and copy shared helpers (`Hooks.java`).
+Override `STELLA_SDK_OUT` to keep the repo clean during local runs.
+
+## Design Principles
+
+- **Builder pattern**: API clients follow idiomatic Java builder patterns for configuration.
+- **OkHttp abstraction**: Uses OkHttp as the HTTP client with interceptor-based hooks.
+- **Jakarta EE**: Uses `jakarta.*` packages for enterprise compatibility.
+- **Deterministic**: Generation is reproducible given the same spec and toolchain lock.
+
+## Helpers
+
+The post-process step copies `Hooks.java` into the output directory providing:
+- `Hooks.withAll()`: Composes auth, telemetry, and retry interceptors onto an OkHttpClient
+- `AuthProvider`: Interface for token-based authentication
+- `RetryOptions`: Configurable retry with exponential backoff
+- `TelemetryOptions`: Client/trace header injection
+- `StellaAuthInterceptor`, `StellaTelemetryInterceptor`, `StellaRetryInterceptor`: OkHttp interceptors
+
+## Maven Coordinates
+
+```xml
+<dependency>
+  <groupId>com.stellaops</groupId>
+  <artifactId>stellaops-sdk</artifactId>
+  <version>0.0.0-alpha</version>
+</dependency>
+```

src/Sdk/StellaOps.Sdk.Generator/java/config.yaml

@@ -0,0 +1,31 @@
+# OpenAPI Generator config for the StellaOps Java SDK (alpha)
+generatorName: java
+outputDir: out/java
+additionalProperties:
+  groupId: com.stellaops
+  artifactId: stellaops-sdk
+  artifactVersion: "0.0.0-alpha"
+  artifactDescription: "StellaOps Java SDK"
+  invokerPackage: com.stellaops.sdk
+  apiPackage: com.stellaops.sdk.api
+  modelPackage: com.stellaops.sdk.model
+  dateLibrary: java8
+  library: okhttp-gson
+  hideGenerationTimestamp: true
+  useRuntimeException: true
+  enumUnknownDefaultCase: true
+  openApiNullable: false
+  supportUrlQuery: true
+  useJakartaEe: true
+  serializationLibrary: gson
+  disallowAdditionalPropertiesIfNotPresent: true
+  java8: true
+  withXml: false
+
+# Post-process hook is supplied via env (STELLA_SDK_POSTPROCESS / postProcessFile)
+
+globalProperty:
+  apiDocs: false
+  modelDocs: false
+  apiTests: false
+  modelTests: false

src/Sdk/StellaOps.Sdk.Generator/java/generate-java.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(cd -- "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+config="$root_dir/java/config.yaml"
+spec="${STELLA_OAS_FILE:-}"
+
+if [ -z "$spec" ]; then
+  echo "STELLA_OAS_FILE is required (path to OpenAPI spec)" >&2
+  exit 1
+fi
+
+output_dir="${STELLA_SDK_OUT:-$root_dir/out/java}"
+mkdir -p "$output_dir"
+
+# Ensure postprocess copies shared helpers into the generated tree
+export STELLA_POSTPROCESS_ROOT="$output_dir"
+export STELLA_POSTPROCESS_LANG="java"
+
+JAR="${STELLA_OPENAPI_GENERATOR_JAR:-$root_dir/tools/openapi-generator-cli-7.4.0.jar}"
+if [ ! -f "$JAR" ]; then
+  echo "OpenAPI Generator CLI jar not found at $JAR" >&2
+  echo "Set STELLA_OPENAPI_GENERATOR_JAR or download to tools/." >&2
+  exit 1
+fi
+
+JAVA_OPTS="${JAVA_OPTS:-} -Dorg.openapitools.codegen.utils.postProcessFile=$root_dir/postprocess/postprocess.sh"
+export JAVA_OPTS
+
+java -jar "$JAR" generate \
+  -i "$spec" \
+  -g java \
+  -c "$config" \
+  --skip-validate-spec \
+  --enable-post-process-file \
+  --global-property models,apis,supportingFiles \
+  -o "$output_dir"
+
+# Ensure shared helpers are present even if upstream post-process hooks were skipped for some files
+if [ -d "$output_dir/src" ]; then
+  "$root_dir/postprocess/postprocess.sh" "$output_dir/src/main/java/com/stellaops/sdk/ApiClient.java" 2>/dev/null || true
+fi
+
+echo "Java SDK generated at $output_dir"

src/Sdk/StellaOps.Sdk.Generator/java/test_generate_java.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(cd -- "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+script="$root_dir/java/generate-java.sh"
+spec="$root_dir/ts/fixtures/ping.yaml"
+jar_default="$root_dir/tools/openapi-generator-cli-7.4.0.jar"
+jar="${STELLA_OPENAPI_GENERATOR_JAR:-$jar_default}"
+
+if [ ! -f "$jar" ]; then
+  echo "SKIP: generator jar not found at $jar" >&2
+  exit 0
+fi
+
+if ! command -v java >/dev/null 2>&1; then
+  echo "SKIP: java not on PATH; set JAVA_HOME to run this smoke." >&2
+  exit 0
+fi
+
+out_dir="$(mktemp -d)"
+trap 'rm -rf "$out_dir"' EXIT
+
+STELLA_OAS_FILE="$spec" \
+STELLA_SDK_OUT="$out_dir" \
+STELLA_OPENAPI_GENERATOR_JAR="$jar" \
+"$script"
+
+# Check that key Java files were generated
+test -f "$out_dir/pom.xml" || { echo "missing generated pom.xml" >&2; exit 1; }
+test -f "$out_dir/src/main/java/com/stellaops/sdk/ApiClient.java" || { echo "missing generated ApiClient.java" >&2; exit 1; }
+test -f "$out_dir/Hooks.java" || { echo "missing Hooks.java helper copy" >&2; exit 1; }
+
+echo "Java generator smoke test passed"