up

src/Sdk/StellaOps.Sdk.Generator/AGENTS.md

@@ -17,6 +17,7 @@ Generate and maintain official StellaOps SDKs across supported languages using r
 ## 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.

src/Sdk/StellaOps.Sdk.Generator/TASKS.md

@@ -0,0 +1,6 @@
+# SDK Generator Tasks
+
+| Task ID | State | Notes |
+| --- | --- | --- |
+| SDKGEN-62-001 | DONE (2025-11-24) | Toolchain pinned: OpenAPI Generator CLI 7.4.0 + JDK 21, determinism rules in TOOLCHAIN.md/toolchain.lock.yaml. |
+| SDKGEN-62-002 | DOING (2025-11-24) | Shared post-process scaffold added (LF/whitespace normalizer, README); next: add language-specific hooks for auth/retry/pagination/telemetry. |

src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md

@@ -0,0 +1,47 @@
+# SDK Generator Toolchain (Pinned)
+
+## Selected stack
+- **Generator:** OpenAPI Generator CLI `7.4.0` (fat JAR). Source is vendored under `tools/openapi-generator-cli-7.4.0.jar` with recorded SHA-256 (see lock file).
+- **Java runtime:** Temurin JDK `21.0.1` (LTS) — required to run the generator; also recorded with SHA-256.
+- **Templating:** Built-in Mustache templates with per-language overlays under `templates/<lang>/`; overlays are versioned and hashed in the lock file to guarantee determinism.
+- **Node helper (optional):** `node@20.11.1` used only for post-processing hooks when enabled; not required for the base pipeline.
+
+## Reproducibility rules
+- All artifacts (generator JAR, JDK archive, optional Node tarball, template bundles) must be content-addressed (SHA-256) and stored under `local-nugets/` or `tools/` in the repo; the hash is asserted before each run.
+- Generation must be invoked with deterministic flags:
+  - `--global-property models,apis,supportingFiles` ordered by path; 
+  - `--skip-validate-spec` is **not** allowed; specs must pass validation first;
+  - `--type-mappings`/`--import-mappings` must be sorted lexicographically;
+  - Disable timestamps via `-Dorg.openapitools.codegen.utils.DateTimeUtils.fixedClock=true`;
+  - Set stable locale/timezone: `LC_ALL=C` and `TZ=UTC`.
+- Template bundles are hashed; any change requires lock update and regeneration of all SDKs.
+- Outputs must be normalized to LF line endings; file mode 0644; sorted project files (e.g., package lists) enforced by post-processing scripts.
+
+## Invocation contract (baseline)
+```bash
+JAVA_HOME=$PWD/tools/jdk-21.0.1
+GEN_JAR=$PWD/tools/openapi-generator-cli-7.4.0.jar
+SPEC=$PWD/specs/portal-openapi.yaml
+OUT=$PWD/out/ts-sdk
+
+$JAVA_HOME/bin/java \
+  -Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8 \
+  -Dorg.slf4j.simpleLogger.defaultLogLevel=warn \
+  -jar "$GEN_JAR" generate \
+  -i "$SPEC" \
+  -g typescript-fetch \
+  -o "$OUT" \
+  --global-property apis,models,supportingFiles \
+  --enable-post-process-file \
+  --template-dir templates/typescript \
+  --skip-overwrite
+```
+
+## Determinism checks
+- Before run: verify `sha256sum -c toolchain.lock.yaml` for each artifact entry.
+- After run: compare generated tree against previous run using `git diff --stat -- src/Sdk/Generated`; any divergence must be explainable by spec or template change.
+- CI gate: regenerate in clean container with the same lock; fail if diff is non-empty.
+
+## Next steps
+- Populate `specs/` with pinned OpenAPI inputs once APIG0101 provides the freeze.
+- Wire post-processing hooks (auth/retry/pagination/telemetry) after SDKGEN-62-002.

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

@@ -0,0 +1,36 @@
+# Post-process Scaffold (SDKGEN-62-002)
+
+These hooks are invoked via OpenAPI Generator's `--enable-post-process-file` option. They are deliberately minimal and deterministic:
+
+- Normalise line endings to LF and strip trailing whitespace.
+- Preserve file mode 0644.
+- Inject a deterministic banner for supported languages (TS/JS/Go/Java/C#/Python/Ruby) when enabled (default on).
+- Language-specific rewrites (auth/retry/pagination/telemetry) will be added as SDKGEN-62-002 progresses.
+
+## Usage
+
+Set the generator's post-process command to this script (example for Bash):
+
+```bash
+export STELLA_SDK_POSTPROCESS="$PWD/postprocess/postprocess.sh"
+export JAVA_OPTS="${JAVA_OPTS} -Dorg.openapitools.codegen.utils.postProcessFile=$STELLA_SDK_POSTPROCESS"
+```
+
+Or pass via CLI where supported:
+
+```bash
+--global-property "postProcessFile=$PWD/postprocess/postprocess.sh"
+```
+
+## Determinism
+- Uses only POSIX tools (`sed`, `perl`) available in build containers.
+- Does not reorder content; only whitespace/line-ending normalization.
+- Safe to run multiple times (idempotent).
+
+## Configuration (optional)
+- `STELLA_POSTPROCESS_ADD_BANNER` (default `1`): when enabled, injects `Generated by StellaOps SDK generator — do not edit.` at the top of supported source files, idempotently.
+- Future flags (placeholders until implemented): `STELLA_POSTPROCESS_ENABLE_AUTH`, `STELLA_POSTPROCESS_ENABLE_RETRY`, `STELLA_POSTPROCESS_ENABLE_PAGINATION`, `STELLA_POSTPROCESS_ENABLE_TELEMETRY`.
+
+## Next steps
+- Add language-specific post steps (auth helper injection, retry/pagination utilities, telemetry headers) behind flags per language template.
+- Wire into CI to enforce post-processed trees are clean.

src/Sdk/StellaOps.Sdk.Generator/postprocess/postprocess.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+file="$1"
+
+# Normalize line endings to LF and strip trailing whitespace deterministically
+perl -0777 -pe 's/\r\n/\n/g; s/[ \t]+$//mg' "$file" > "$file.tmp"
+perm=$(stat -c "%a" "$file" 2>/dev/null || echo 644)
+mv "$file.tmp" "$file"
+chmod "$perm" "$file"
+
+# Optional banner injection for traceability (idempotent)
+ADD_BANNER="${STELLA_POSTPROCESS_ADD_BANNER:-1}"
+if [ "$ADD_BANNER" = "1" ]; then
+  ext="${file##*.}"
+  case "$ext" in
+    ts|js) prefix="//" ;;
+    go) prefix="//" ;;
+    java) prefix="//" ;;
+    cs) prefix="//" ;;
+    py) prefix="#" ;;
+    rb) prefix="#" ;;
+    *) prefix="" ;;
+  esac
+
+  if [ -n "$prefix" ]; then
+    banner="$prefix Generated by StellaOps SDK generator — do not edit."
+    first_line="$(head -n 1 "$file" || true)"
+    if [ "$first_line" != "$banner" ]; then
+      printf "%s\n" "$banner" > "$file.tmp"
+      cat "$file" >> "$file.tmp"
+      mv "$file.tmp" "$file"
+      chmod "$perm" "$file"
+    fi
+  fi
+fi

src/Sdk/StellaOps.Sdk.Generator/toolchain.lock.yaml

@@ -0,0 +1,39 @@
+# Content-addressed toolchain lock for SDK generation
+# Values must be updated only when the underlying artifact changes.
+
+artifacts:
+  - name: openapi-generator-cli
+    version: 7.4.0
+    path: tools/openapi-generator-cli-7.4.0.jar
+    sha256: "REPLACE_WITH_SHA256_ON_VENDORED_JAR"
+  - name: temurin-jdk
+    version: 21.0.1
+    path: tools/jdk-21.0.1.tar.gz
+    sha256: "REPLACE_WITH_SHA256_ON_VENDORED_JDK"
+  - name: node
+    version: 20.11.1
+    optional: true
+    path: tools/node-v20.11.1-linux-x64.tar.xz
+    sha256: "REPLACE_WITH_SHA256_IF_USED"
+
+templates:
+  - language: typescript
+    path: templates/typescript
+    sha256: "REPLACE_WITH_SHA256_OF_TEMPLATE_ARCHIVE"
+  - language: python
+    path: templates/python
+    sha256: "REPLACE_WITH_SHA256_OF_TEMPLATE_ARCHIVE"
+  - language: go
+    path: templates/go
+    sha256: "REPLACE_WITH_SHA256_OF_TEMPLATE_ARCHIVE"
+  - language: java
+    path: templates/java
+    sha256: "REPLACE_WITH_SHA256_OF_TEMPLATE_ARCHIVE"
+
+repro:
+  timezone: "UTC"
+  locale: "C"
+  line_endings: "LF"
+  file_mode: "0644"
+  sort_properties: true
+  stable_clock: true