up

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

@@ -1,11 +1,11 @@
 # 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:
+These hooks are invoked via OpenAPI Generator's `--enable-post-process-file` option. They stay deterministic and offline-friendly:
 
 - 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.
+- Copy shared SDK helpers (auth, retries, pagination, telemetry) per language into the generated output when `STELLA_POSTPROCESS_ROOT` and `STELLA_POSTPROCESS_LANG` are provided. TypeScript/Python exports are auto-wired so helpers are available from the package barrel.
 
 ## Usage
 
@@ -22,15 +22,30 @@ Or pass via CLI where supported:
 --global-property "postProcessFile=$PWD/postprocess/postprocess.sh"
 ```
 
+To copy shared helpers during post-processing, also set the generation root and language:
+
+```bash
+export STELLA_POSTPROCESS_ROOT="/path/to/generated/sdk"
+export STELLA_POSTPROCESS_LANG="ts"   # ts|python|go|java|csharp|ruby
+```
+
 ## 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`.
+- `STELLA_POSTPROCESS_ADD_BANNER` (default `1`): injects `Generated by StellaOps SDK generator — do not edit.` at the top of supported source files, idempotently.
+- `STELLA_POSTPROCESS_ROOT`: root directory of the generated SDK; required to copy helper files.
+- `STELLA_POSTPROCESS_LANG`: one of `ts|python|go|java|csharp|ruby`; controls which helper set is copied.
+
+## Helper contents (per language)
+- **TypeScript** (`templates/typescript/sdk-hooks.ts`, `sdk-error.ts`, package/tsconfig templates, README): fetch composers for auth, retries, telemetry headers, paginator, and a minimal typed error class. Packaging files provide ESM/CJS outputs with deterministic settings.
+- **Python** (`templates/python/sdk_hooks.py`): transport-agnostic wrappers for auth, retries, telemetry headers, and cursor pagination.
+- **Go** (`templates/go/hooks.go`): http.RoundTripper helpers for auth, telemetry, retries, and a generic paginator.
+- **Java** (`templates/java/Hooks.java`): OkHttp interceptors for auth, telemetry, retries, plus a helper to compose them.
+- C#/Ruby templates are reserved for follow-on language tracks; the banner logic already supports them.
 
 ## 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.
+- Add C#/Ruby helpers once those language tracks start.
+- Wire postprocess tests into CI to enforce clean, deterministic outputs.