Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
api-governance / spectral-lint (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
api-governance / spectral-lint (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
This commit is contained in:
StellaOps Bot
@@ -1,27 +1,27 @@
|
||||
# SDK Generator Guild Charter
|
||||
|
||||
## Mission
|
||||
Generate and maintain official StellaOps SDKs across supported languages using reproducible code generation pipelines.
|
||||
|
||||
## Scope
|
||||
- Manage code generation templates and tooling for TS, Python, Go, Java (C#/Rust follow-ons).
|
||||
- Implement post-processing hooks for auth helpers, retries, paginators, error mapping, and telemetry.
|
||||
- Provide language-specific smoke tests, example snippets, and continuous integration.
|
||||
- Coordinate with Release Guild for publishing and version bumps.
|
||||
|
||||
## Definition of Done
|
||||
- SDKs regenerate deterministically from `stella.yaml` without manual edits.
|
||||
- Smoke tests and integration suites run per language in CI.
|
||||
- Generated code adheres to language-specific style guides and passes lint/format checks.
|
||||
|
||||
# SDK Generator Guild Charter
|
||||
|
||||
## Mission
|
||||
Generate and maintain official StellaOps SDKs across supported languages using reproducible code generation pipelines.
|
||||
|
||||
## Scope
|
||||
- Manage code generation templates and tooling for TS, Python, Go, Java (C#/Rust follow-ons).
|
||||
- Implement post-processing hooks for auth helpers, retries, paginators, error mapping, and telemetry.
|
||||
- Provide language-specific smoke tests, example snippets, and continuous integration.
|
||||
- Coordinate with Release Guild for publishing and version bumps.
|
||||
|
||||
## Definition of Done
|
||||
- SDKs regenerate deterministically from `stella.yaml` without manual edits.
|
||||
- Smoke tests and integration suites run per language in CI.
|
||||
- Generated code adheres to language-specific style guides and passes lint/format checks.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
- `src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md` (pinned toolchain, determinism rules)
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both correspoding sprint file `/docs/implplan/SPRINT_*.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both correspoding sprint file `/docs/implplan/SPRINT_*.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,26 +1,35 @@
|
||||
# Go SDK (SDKGEN-63-003)
|
||||
|
||||
Deterministic generator settings for the Go SDK.
|
||||
|
||||
## Prereqs
|
||||
- `STELLA_OAS_FILE` pointing to the frozen OpenAPI spec.
|
||||
- Optional but recommended: `STELLA_OAS_EXPECTED_SHA256` set to the pinned spec hash; the script will verify and emit `.oas.sha256` in the output.
|
||||
- OpenAPI Generator CLI 7.4.0 jar at `tools/openapi-generator-cli-7.4.0.jar` (override with `STELLA_OPENAPI_GENERATOR_JAR`).
|
||||
- JDK 21 on PATH (or vendored at `../tools/jdk-21.0.1+12`).
|
||||
|
||||
## Generate
|
||||
```bash
|
||||
cd src/Sdk/StellaOps.Sdk.Generator
|
||||
STELLA_OAS_FILE=ts/fixtures/ping.yaml \
|
||||
STELLA_SDK_OUT=$(mktemp -d) \
|
||||
STELLA_OAS_EXPECTED_SHA256=$(sha256sum ts/fixtures/ping.yaml | awk '{print $1}') \
|
||||
go/generate-go.sh
|
||||
```
|
||||
|
||||
Outputs land in `out/go/` (or `STELLA_SDK_OUT`) and are post-processed to normalize whitespace, inject the banner, copy shared hooks (`hooks.go`), and record the spec hash in `.oas.sha256`.
|
||||
|
||||
## Smoke test
|
||||
```bash
|
||||
cd src/Sdk/StellaOps.Sdk.Generator/go
|
||||
./test_generate_go.sh # skips if generator jar or JDK is missing
|
||||
```
|
||||
# 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
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
packageName: stellaops
|
||||
enumClassPrefix: true
|
||||
sourceFolder: src
|
||||
withGoMod: true
|
||||
additionalProperties:
|
||||
# Keep generated code lean and deterministic for alpha
|
||||
packageVersion: 0.1.0-alpha
|
||||
hideGenerationTimestamp: true
|
||||
useOneOfDiscriminatorLookup: true
|
||||
# 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
|
||||
|
||||
@@ -1,77 +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
|
||||
|
||||
compute_sha256() {
|
||||
if command -v sha256sum >/dev/null 2>&1; then
|
||||
sha256sum "$1" | awk '{print $1}'
|
||||
elif command -v shasum >/dev/null 2>&1; then
|
||||
shasum -a 256 "$1" | awk '{print $1}'
|
||||
else
|
||||
echo "No sha256 tool available (install sha256sum or shasum)" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
spec_hash=$(compute_sha256 "$spec")
|
||||
expected_hash="${STELLA_OAS_EXPECTED_SHA256:-}"
|
||||
if [ -n "$expected_hash" ] && [ "$expected_hash" != "$spec_hash" ]; then
|
||||
echo "Spec hash mismatch: expected $expected_hash but got $spec_hash" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
output_dir="${STELLA_SDK_OUT:-$root_dir/out/go}"
|
||||
mkdir -p "$output_dir"
|
||||
printf "%s %s\n" "$spec_hash" "$(basename "$spec")" > "$output_dir/.oas.sha256"
|
||||
|
||||
# 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
|
||||
|
||||
# Prefer vendored JDK when java is absent
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
vendor_jdk="$root_dir/tools/jdk-21.0.1+12"
|
||||
if [ -d "$vendor_jdk/bin" ]; then
|
||||
export JAVA_HOME="$vendor_jdk"
|
||||
export PATH="$JAVA_HOME/bin:$PATH"
|
||||
fi
|
||||
fi
|
||||
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
echo "java not found; install JDK 21 or provide vendored tools/jdk-21.0.1+12" >&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 [ -f "$output_dir/client.go" ]; then
|
||||
"$root_dir/postprocess/postprocess.sh" "$output_dir/client.go"
|
||||
fi
|
||||
|
||||
echo "Go SDK generated at $output_dir"
|
||||
#!/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"
|
||||
|
||||
@@ -1,51 +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}"
|
||||
|
||||
compute_sha256() {
|
||||
if command -v sha256sum >/dev/null 2>&1; then
|
||||
sha256sum "$1" | awk '{print $1}'
|
||||
else
|
||||
shasum -a 256 "$1" | awk '{print $1}'
|
||||
fi
|
||||
}
|
||||
expected_hash=$(compute_sha256 "$spec")
|
||||
|
||||
if [ ! -f "$jar" ]; then
|
||||
echo "SKIP: generator jar not found at $jar" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# If java is missing, try vendored JDK in tools/
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
vendor_jdk="$root_dir/tools/jdk-21.0.1+12"
|
||||
if [ -d "$vendor_jdk/bin" ]; then
|
||||
export JAVA_HOME="$vendor_jdk"
|
||||
export PATH="$JAVA_HOME/bin:$PATH"
|
||||
fi
|
||||
fi
|
||||
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
echo "SKIP: java not on PATH and vendored JDK not found; set JAVA_HOME or install JDK 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" \
|
||||
STELLA_OAS_EXPECTED_SHA256="$expected_hash" \
|
||||
JAVA_OPTS="${JAVA_OPTS:-} -Dorg.openapitools.codegen.utils.postProcessFile=$root_dir/postprocess/postprocess.sh" \
|
||||
"$script"
|
||||
|
||||
test -f "$out_dir/.oas.sha256" || { echo "missing spec hash output" >&2; exit 1; }
|
||||
test -f "$out_dir/hooks/hooks.go" || test -f "$out_dir/hooks.go" || { echo "missing helper copy" >&2; exit 1; }
|
||||
|
||||
echo "Go generator smoke test passed"
|
||||
#!/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"
|
||||
|
||||
@@ -1,26 +1,45 @@
|
||||
# Java SDK (SDKGEN-63-004)
|
||||
|
||||
Deterministic generator settings for the Java SDK (okhttp-gson client).
|
||||
|
||||
## Prereqs
|
||||
- `STELLA_OAS_FILE` pointing to the frozen OpenAPI spec.
|
||||
- Optional but recommended: `STELLA_OAS_EXPECTED_SHA256` set to the pinned spec hash; the script will verify and emit `.oas.sha256` in the output.
|
||||
- OpenAPI Generator CLI 7.4.0 jar at `tools/openapi-generator-cli-7.4.0.jar` (override with `STELLA_OPENAPI_GENERATOR_JAR`).
|
||||
- JDK 21 on PATH (or vendored at `../tools/jdk-21.0.1+12`).
|
||||
|
||||
## Generate
|
||||
```bash
|
||||
cd src/Sdk/StellaOps.Sdk.Generator
|
||||
STELLA_OAS_FILE=ts/fixtures/ping.yaml \
|
||||
STELLA_SDK_OUT=$(mktemp -d) \
|
||||
STELLA_OAS_EXPECTED_SHA256=$(sha256sum ts/fixtures/ping.yaml | awk '{print $1}') \
|
||||
java/generate-java.sh
|
||||
```
|
||||
|
||||
Outputs land in `out/java/` (or `STELLA_SDK_OUT`) and are post-processed to normalize whitespace, inject the banner, copy shared hooks (`Hooks.java` under `org.stellaops.sdk`), and record the spec hash in `.oas.sha256`.
|
||||
|
||||
## Smoke test
|
||||
```bash
|
||||
cd src/Sdk/StellaOps.Sdk.Generator/java
|
||||
./test_generate_java.sh # skips if generator jar or JDK is missing
|
||||
```
|
||||
# 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>
|
||||
```
|
||||
|
||||
@@ -1,12 +1,31 @@
|
||||
groupId: org.stellaops
|
||||
artifactId: stellaops-sdk
|
||||
artifactVersion: 0.1.0-alpha
|
||||
invokerPackage: org.stellaops.sdk
|
||||
modelPackage: org.stellaops.sdk.model
|
||||
apiPackage: org.stellaops.sdk.api
|
||||
library: okhttp-gson
|
||||
hideGenerationTimestamp: true
|
||||
dateLibrary: java8
|
||||
useRuntimeException: true
|
||||
serializationLibrary: gson
|
||||
useJakartaEe: true
|
||||
# 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
|
||||
|
||||
@@ -1,76 +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
|
||||
|
||||
compute_sha256() {
|
||||
if command -v sha256sum >/dev/null 2>&1; then
|
||||
sha256sum "$1" | awk '{print $1}'
|
||||
elif command -v shasum >/dev/null 2>&1; then
|
||||
shasum -a 256 "$1" | awk '{print $1}'
|
||||
else
|
||||
echo "No sha256 tool available (install sha256sum or shasum)" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
spec_hash=$(compute_sha256 "$spec")
|
||||
expected_hash="${STELLA_OAS_EXPECTED_SHA256:-}"
|
||||
if [ -n "$expected_hash" ] && [ "$expected_hash" != "$spec_hash" ]; then
|
||||
echo "Spec hash mismatch: expected $expected_hash but got $spec_hash" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
output_dir="${STELLA_SDK_OUT:-$root_dir/out/java}"
|
||||
mkdir -p "$output_dir"
|
||||
printf "%s %s\n" "$spec_hash" "$(basename "$spec")" > "$output_dir/.oas.sha256"
|
||||
|
||||
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
|
||||
|
||||
# Prefer vendored JDK when java is absent
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
vendor_jdk="$root_dir/tools/jdk-21.0.1+12"
|
||||
if [ -d "$vendor_jdk/bin" ]; then
|
||||
export JAVA_HOME="$vendor_jdk"
|
||||
export PATH="$JAVA_HOME/bin:$PATH"
|
||||
fi
|
||||
fi
|
||||
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
echo "java not found; install JDK 21 or provide vendored tools/jdk-21.0.1+12" >&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 [ -f "$output_dir/src/main/java/org/stellaops/sdk/ApiClient.java" ]; then
|
||||
"$root_dir/postprocess/postprocess.sh" "$output_dir/src/main/java/org/stellaops/sdk/ApiClient.java"
|
||||
fi
|
||||
|
||||
echo "Java SDK generated at $output_dir"
|
||||
#!/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"
|
||||
|
||||
@@ -1,51 +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}"
|
||||
|
||||
compute_sha256() {
|
||||
if command -v sha256sum >/dev/null 2>&1; then
|
||||
sha256sum "$1" | awk '{print $1}'
|
||||
else
|
||||
shasum -a 256 "$1" | awk '{print $1}'
|
||||
fi
|
||||
}
|
||||
expected_hash=$(compute_sha256 "$spec")
|
||||
|
||||
if [ ! -f "$jar" ]; then
|
||||
echo "SKIP: generator jar not found at $jar" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# If java is missing, try vendored JDK in tools/
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
vendor_jdk="$root_dir/tools/jdk-21.0.1+12"
|
||||
if [ -d "$vendor_jdk/bin" ]; then
|
||||
export JAVA_HOME="$vendor_jdk"
|
||||
export PATH="$JAVA_HOME/bin:$PATH"
|
||||
fi
|
||||
fi
|
||||
|
||||
if ! command -v java >/dev/null 2>&1; then
|
||||
echo "SKIP: java not on PATH and vendored JDK not found; set JAVA_HOME or install JDK 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" \
|
||||
STELLA_OAS_EXPECTED_SHA256="$expected_hash" \
|
||||
JAVA_OPTS="${JAVA_OPTS:-} -Dorg.openapitools.codegen.utils.postProcessFile=$root_dir/postprocess/postprocess.sh" \
|
||||
"$script"
|
||||
|
||||
test -f "$out_dir/.oas.sha256" || { echo "missing spec hash output" >&2; exit 1; }
|
||||
test -f "$out_dir/src/main/java/org/stellaops/sdk/Hooks.java" || { echo "missing helper copy" >&2; exit 1; }
|
||||
|
||||
echo "Java generator smoke test passed"
|
||||
#!/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"
|
||||
|
||||
@@ -1,26 +1,26 @@
|
||||
# SDK Release Guild Charter
|
||||
|
||||
## Mission
|
||||
Own packaging, signing, publishing, and changelog automation for official StellaOps SDKs and dev portal bundles.
|
||||
|
||||
## Scope
|
||||
- Manage language-specific release pipelines (npm, PyPI, Maven, Go modules) with provenance signing.
|
||||
- Automate changelog generation and SemVer version bumps aligned with API releases.
|
||||
- Coordinate publication of offline bundles for air-gapped environments.
|
||||
- Operate release dashboards and notification hooks for SDK updates.
|
||||
|
||||
## Definition of Done
|
||||
- Every SDK release is reproducible, signed, and accompanied by changelog + provenance.
|
||||
- Registries updated via automated pipeline with rollback strategy.
|
||||
- Offline bundle creation integrated with Export Center workflows.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both correspoding sprint file `/docs/implplan/SPRINT_*.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
# SDK Release Guild Charter
|
||||
|
||||
## Mission
|
||||
Own packaging, signing, publishing, and changelog automation for official StellaOps SDKs and dev portal bundles.
|
||||
|
||||
## Scope
|
||||
- Manage language-specific release pipelines (npm, PyPI, Maven, Go modules) with provenance signing.
|
||||
- Automate changelog generation and SemVer version bumps aligned with API releases.
|
||||
- Coordinate publication of offline bundles for air-gapped environments.
|
||||
- Operate release dashboards and notification hooks for SDK updates.
|
||||
|
||||
## Definition of Done
|
||||
- Every SDK release is reproducible, signed, and accompanied by changelog + provenance.
|
||||
- Registries updated via automated pipeline with rollback strategy.
|
||||
- Offline bundle creation integrated with Export Center workflows.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both correspoding sprint file `/docs/implplan/SPRINT_*.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
Reference in New Issue
Block a user