# SDK Generator Toolchain (Multi-Language)

## Module
Sdk

## Status
VERIFIED

## Description
Multi-language SDK generator toolchain producing typed API clients in TypeScript, Python, Go, and Java from OpenAPI specifications, with postprocessing, release pipelines, and offline bundle support.

## Implementation Details
- **Go Generator**: `src/Sdk/StellaOps.Sdk.Generator/go/` -- Go SDK generation configuration and scripts. Key files: `config.yaml` (OpenAPI Generator config for Go), `generate-go.sh` (generation script), `test_generate_go.sh` (test script).
- **Java Generator**: `src/Sdk/StellaOps.Sdk.Generator/java/` -- Java SDK generation. Key files: `config.yaml`, `generate-java.sh`, `test_generate_java.sh`.
- **Python Generator**: `src/Sdk/StellaOps.Sdk.Generator/python/` -- Python SDK generation. Key files: `config.yaml`, `generate-python.sh`, `test_generate_python.sh`.
- **Postprocessing Pipeline**: `src/Sdk/StellaOps.Sdk.Generator/postprocess/` -- post-generation processing adding hooks, error handling, and SDK-specific customizations. Key files: `postprocess.sh` (orchestrator), `README.md` (documentation).
- **Postprocessing Templates**: `src/Sdk/StellaOps.Sdk.Generator/postprocess/templates/` -- language-specific hook templates: `go/hooks.go`, `java/src/main/java/org/stellaops/sdk/Hooks.java`, `python/sdk_hooks.py`, `typescript/sdk-hooks.ts`, `typescript/sdk-error.ts`, `typescript/package.json`, `typescript/tsconfig.*.json`.
- **Toolchain Lock**: `src/Sdk/StellaOps.Sdk.Generator/toolchain.lock.yaml` -- pinned versions of generator tools for reproducible builds.
- **Toolchain Documentation**: `src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md` -- documentation of the toolchain, versions, and upgrade process.
- **Vendored Tools**: `src/Sdk/StellaOps.Sdk.Generator/tools/openapi-generator-cli-7.4.0.jar` (OpenAPI Generator), `tools/jdk-21.0.1.tar.gz` (JDK for Java generation).
- **Postprocessing Tests**: `src/Sdk/StellaOps.Sdk.Generator/postprocess/tests/test_postprocess.sh` -- tests for postprocessing pipeline.

## E2E Test Plan
- [x] Run the Go SDK generation script (`generate-go.sh`) against the OpenAPI spec and verify it produces a compilable Go client package
- [x] Run the Java SDK generation script and verify the output compiles with the vendored JDK
- [x] Run the Python SDK generation script and verify the output is a valid Python package with correct module structure
- [x] Run the postprocessing pipeline on a generated TypeScript SDK and verify hooks, error handling, and package.json are correctly injected
- [x] Verify toolchain pinning inputs are present (`toolchain.lock.yaml`, vendored generator jar, vendored JDK tarball) and consumed by generator smoke workflows
- [x] Run all test scripts (`test_generate_ts.sh`, `test_generate_go.sh`, `test_generate_java.sh`, `test_generate_python.sh`, `test_postprocess.sh`) and verify they pass
- [x] Verify offline-capable generation path uses local fixture spec and vendored generator artifacts

## Verification
- **Run ID**: run-002
- **Date**: 2026-02-11
- **Method**: Tier 0 source verification + Tier 1/Tier 2 shell-based generator smoke replay
- **Build/Test**: PASS (5/5 script-based generator/postprocess smoke checks)
- **Tier 0 Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier0-source-check.json`
- **Tier 1 Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier1-build-check.json`
- **Tier 2 Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier2-integration-check.json`
- **Command Output Evidence**: `docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/evidence/`

## Recheck Notes
- Initial replay attempt (`_run-001_capture`) exposed a host-shell interoperability bug: Go/Java scripts were CRLF, causing `set -euo pipefail` parsing failures in Bash.
- Fix applied: normalized LF endings for:
  - `src/Sdk/StellaOps.Sdk.Generator/go/test_generate_go.sh`
  - `src/Sdk/StellaOps.Sdk.Generator/java/test_generate_java.sh`
  - `src/Sdk/StellaOps.Sdk.Generator/go/generate-go.sh`
  - `src/Sdk/StellaOps.Sdk.Generator/java/generate-java.sh`
- Retest (`run-002`) passed all generator/postprocess smoke checks with fresh evidence.

## Recheck (Run-003)
- **Verified**: 2026-02-11
- **Method**: Strict Tier 2 shell-based behavioral replay with vendored JDK setup and explicit negative-path coverage.
- **Build/Test**: PASS (7/7 script smokes): `test_line_endings.sh`, `test_generate_ts.sh`, `test_generate_go.sh`, `test_generate_java.sh`, `test_generate_python.sh`, `test_postprocess.sh`, `test_generate_ts_hash_mismatch.sh`.
- **Tier 0 Evidence**: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier0-source-check.json
- **Tier 1 Evidence**: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier1-build-check.json
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier2-integration-check.json
- **Outcome**: Recheck remained green with new regression guards for LF line endings and TS spec-hash mismatch handling.