stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
92bc4d3a0703a414969cdcbed3571a0fe382cda7
git.stella-ops.org/docs/implplan/SPRINT_0208_0001_0001_sdk.md
master b7059d523e Refactor and update test projects, remove obsolete tests, and upgrade dependencies 
- Deleted obsolete test files for SchedulerAuditService and SchedulerMongoSessionFactory.
- Removed unused TestDataFactory class.
- Updated project files for Mongo.Tests to remove references to deleted files.
- Upgraded BouncyCastle.Cryptography package to version 2.6.2 across multiple projects.
- Replaced Microsoft.Extensions.Http.Polly with Microsoft.Extensions.Http.Resilience in Zastava.Webhook project.
- Updated NetEscapades.Configuration.Yaml package to version 3.1.0 in Configuration library.
- Upgraded Pkcs11Interop package to version 5.1.2 in Cryptography libraries.
- Refactored Argon2idPasswordHasher to use BouncyCastle for hashing instead of Konscious.
- Updated JsonSchema.Net package to version 7.3.2 in Microservice project.
- Updated global.json to use .NET SDK version 10.0.101.
2025-12-10 19:13:29 +02:00

16 KiB
Raw Blame History

Sprint 0208 · Experience & SDKs

Topic & Scope

  • Build a reproducible SDK generator toolchain and shared post-processing layer that stays air-gap safe.
  • Ship alpha SDKs (TypeScript, Python, Go, Java) aligned to portal APIs with consistent auth/telemetry helpers.
  • Connect SDK outputs to CLI and Console data providers; package offline delivery bundles with provenance.
  • Evidence: updated generator pipelines, release configs, and signed artifacts across npm/PyPI/Maven/Go proxies.
  • Working directory: docs/implplan (planning) with execution in src/Sdk/StellaOps.Sdk.*.

Dependencies & Concurrency

  • Upstream sprints: Sprint 120.A (AirGap), 130.A (Scanner), 150.A (Orchestrator), 170.A (Notifier) for API and events readiness.
  • Peer/consuming sprints: SPRINT_0201_0001_0001_cli_i (CLI), SPRINT_0206_0001_0001_devportal (devportal/offline bundles), SPRINT_0209_0001_0001_ui_i (Console/UI data providers).
  • Concurrency: language tracks can parallelize after SDKGEN-62-002; release tasks follow generator readiness; consumer sprints can prototype against staging SDKs once B wave exits.

Documentation Prerequisites

  • docs/README.md; docs/07_HIGH_LEVEL_ARCHITECTURE.md; docs/modules/platform/architecture-overview.md.
  • docs/modules/cli/architecture.md; docs/modules/ui/architecture.md.
  • API/OAS governance specs referenced by APIG0101 and portal contracts (DEVL0101) once published.

Delivery Tracker

# Task ID Status Key dependency / next step Owners Task Definition
1 SDKGEN-62-001 DONE (2025-11-24) Toolchain, template layout, and reproducibility spec pinned. SDK Generator Guild · src/Sdk/StellaOps.Sdk.Generator Choose/pin generator toolchain, set up language template pipeline, and enforce reproducible builds.
2 SDKGEN-62-002 DONE (2025-11-24) Shared post-processing merged; helpers wired. SDK Generator Guild Implement shared post-processing (auth helpers, retries, pagination utilities, telemetry hooks) applied to all languages.
3 SDKGEN-63-001 TODO Unblocked by CONTRACT-API-GOVERNANCE-BASELINE-012; follow freeze process to generate TS alpha. SDK Generator Guild Ship TypeScript SDK alpha with ESM/CJS builds, typed errors, paginator, streaming helpers.
4 SDKGEN-63-002 TODO Unblocked by CONTRACT-API-GOVERNANCE-BASELINE-012; follow freeze process to generate Python alpha. SDK Generator Guild Ship Python SDK alpha (sync/async clients, type hints, upload/download helpers).
5 SDKGEN-63-003 TODO Unblocked by CONTRACT-API-GOVERNANCE-BASELINE-012; follow freeze process to generate Go alpha. SDK Generator Guild Ship Go SDK alpha with context-first API and streaming helpers.
6 SDKGEN-63-004 TODO Unblocked by CONTRACT-API-GOVERNANCE-BASELINE-012; follow freeze process to generate Java alpha. SDK Generator Guild Ship Java SDK alpha (builder pattern, HTTP client abstraction).
7 SDKGEN-64-001 TODO Unblocked; can proceed after 63-004 with CONTRACT-API-GOVERNANCE-BASELINE-012. SDK Generator Guild · CLI Guild Switch CLI to consume TS or Go SDK; ensure parity once Wave B artifacts land.
8 SDKGEN-64-002 TODO Unblocked; can proceed after 64-001. SDK Generator Guild · Console Guild Integrate SDKs into Console data providers where feasible.
9 SDKREL-63-001 TODO Dev key available at tools/cosign/cosign.dev.key for staging; production keys pending Action #7. SDK Release Guild · src/Sdk/StellaOps.Sdk.Release Configure CI pipelines for npm, PyPI, Maven Central staging, and Go proxies with signing and provenance attestations.
10 SDKREL-63-002 TODO Unblocked; can proceed after 63-001 with dev key for staging. SDK Release Guild · API Governance Guild Integrate changelog automation pulling from OAS diffs and generator metadata.
11 SDKREL-64-001 TODO Unblocked; can proceed after 63-001 with dev key for staging. SDK Release Guild · Notifications Guild Hook SDK releases into Notifications Studio with scoped announcements and RSS/Atom feeds.
12 SDKREL-64-002 TODO Unblocked; can proceed after SDKGEN-64-001 with dev key for staging. SDK Release Guild · Export Center Guild Add devportal --offline bundle job packaging docs, specs, SDK artifacts for air-gapped users.

Wave Coordination

  • Single wave covering generator and release work; language tracks branch after SDKGEN-62-002.

Wave Detail Snapshots

Wave Window (UTC) Scope Exit criteria Owners Status
A: Generator foundation 2025-11-25 → 2025-12-02 SDKGEN-62-001..002 (toolchain pin, shared post-processing) Toolchain pinned; reproducibility spec approved; shared layer merged. SDK Generator Guild Planned
B: Language alphas 2025-12-03 → 2025-12-22 SDKGEN-63-001..004 (TS, Python, Go, Java alphas) All four alphas published to staging registries with parity matrix signed off. SDK Generator Guild Planned
C: Release & offline 2025-12-08 → 2025-12-29 SDKREL-63-001..64-002 (CI, changelog, notifications, offline bundle) CI pipelines green in staging; changelog automation live; notifications wired; offline bundle produced; manifest template in docs/modules/export-center/devportal-offline-manifest.md adopted. SDK Release Guild · Export Center Guild Planned

Interlocks

  • API governance: APIG0101 outputs for stable schemas; required before Wave A exit.
  • Portal contracts: DEVL0101 (auth/session) inform shared post-processing; consume before Wave A design review.
  • Devportal/offline: SPRINT_0206_0001_0001_devportal must expose bundle manifest format for SDKREL-64-002.
  • CLI adoption: SPRINT_0201_0001_0001_cli_i aligns surfaces for SDKGEN-64-001; needs Wave B artifacts.
  • Console data providers: SPRINT_0209_0001_0001_ui_i depends on SDKGEN-64-002; needs parity matrix from Wave B.
  • Notifications/Export: Notifications Studio and Export Center pipelines must be live before Wave C release window (tasks 11–12).
  • Aggregate OAS freeze: APIG0101 must publish tagged snapshot + SHA (Action #6) to unblock SDKGEN-63-001..004 generation.
  • Signing keys: Sovereign crypto key provisioning for npm/PyPI/Maven/Go (Action #7) gates SDKREL-63-001 staging runs.

Upcoming Checkpoints

  • 2025-12-05: TS alpha staging drop (SDKGEN-63-001) — verify packaging and typed errors (BLOCKED until aggregate OAS freeze).
  • 2025-12-15: Multi-language alpha readiness check (SDKGEN-63-002..004) — parity matrix sign-off (BLOCKED until aggregate OAS freeze and Java alpha generation).
  • 2025-12-16: Deliver parity matrix and SDK drop to UI/Console data providers (depends on Wave B artifacts).
  • 2025-12-22: Release automation demo (SDKREL-63/64) — staging publishes with signatures and offline bundle (BLOCKED until SDKREL-63-001/002 advance).

Action Tracker

# Action Owner Due (UTC) Status
1 Confirm registry signing keys and provenance workflow per language SDK Release Guild 2025-11-29 BLOCKED (awaiting sovereign crypto key provisioning; overdue)
2 Publish SDK language support matrix to CLI/UI guilds. Evidence: docs/modules/sdk/language-support-matrix.md. SDK Generator Guild 2025-12-03 DONE (2025-11-26)
3 Align CLI adoption scope with SPRINT_0201_0001_0001_cli_i and schedule SDK drop integration SDK Generator Guild · CLI Guild 2025-12-10 Open
4 Define devportal offline bundle manifest with Export Center per SPRINT_0206_0001_0001_devportal. Evidence: docs/modules/export-center/devportal-offline-manifest.md. SDK Release Guild · Export Center Guild 2025-12-12 DONE (2025-11-26)
5 Deliver parity matrix and SDK drop to UI data providers per SPRINT_0209_0001_0001_ui_i SDK Generator Guild · UI Guild 2025-12-16 Open
6 Request tagged aggregate OpenAPI snapshot + SHA from APIG0101 to unblock Wave B generation API Governance Guild · SDK Generator Guild 2025-12-02 Open
7 Escalate sovereign crypto key provisioning for npm/PyPI/Maven/Go signing to unblock SDKREL-63-001 SDK Release Guild · Platform Security 2025-12-02 Open

Decisions & Risks

  • Toolchain pinned (OpenAPI Generator 7.4.0, JDK 21) and recorded in repo (TOOLCHAIN.md, toolchain.lock.yaml); downstream tracks must honor lock file for determinism.
  • Dependencies on upstream API/portal contracts may delay generator pinning; mitigation: align with APIG0101 / DEVL0101 milestones.
  • Release automation requires registry credentials and signing infra; keys still pending (Action Tracker #1 overdue). Mitigation: reuse sovereign crypto enablement (SPRINT_0514_0001_0001_sovereign_crypto_enablement.md) practices, escalate key provisioning by 2025-12-02, and block releases until keys are validated.
  • Offline bundle job (SDKREL-64-002) depends on Export Center artifacts; track alongside Export Center sprints; remains BLOCKED until SDKGEN-64-001 completes.
  • Shared postprocess helpers copy only when CI sets STELLA_POSTPROCESS_ROOT and STELLA_POSTPROCESS_LANG; ensure generation jobs export these to keep helpers present in artifacts.
  • Aggregate OAS freeze now on critical path for Wave B; request tagged snapshot with SHA (Action #6) by 2025-12-02 to unblock SDKGEN-63-001..004.
  • Sprint fully unblocked for development/staging: CONTRACT-API-GOVERNANCE-BASELINE-012 provides freeze process for OAS snapshot. Development signing key available at tools/cosign/cosign.dev.key (password: stellaops-dev). Production releases still require sovereign key provisioning (Action #7).

Risk Register

Risk Impact Mitigation Owner Status
Upstream APIs change after generator pin Rework across four SDKs Freeze spec version before SDKGEN-63-x; gate via API governance sign-off SDK Generator Guild Open
Aggregate OpenAPI freeze delayed Wave B and downstream adoption blocked Track APIG0101 schedule; request interim tagged snapshot with SHA; re-run hash guard once frozen SDK Generator Guild Open
Registry signing not provisioned Cannot ship to npm/PyPI/Maven/Go Coordinate with sovereign crypto enablement; dry-run staging before prod; Action #7 escalation due 2025-12-02 SDK Release Guild Open
Offline bundle inputs unavailable Air-gapped delivery slips Pull docs/specs from devportal cache; coordinate with Export Center; tied to SDKREL-64-002 blocker SDK Release Guild Open

Execution Log

Date (UTC) Update Owner
2025-11-22 Normalised sprint to standard template; renamed file to SPRINT_0208_0001_0001_sdk.md; no status changes. PM
2025-11-22 Added wave plan and dated checkpoints for generator, language alphas, and release/offline tracks. PM
2025-11-22 Added explicit interlocks to CLI/UI/Devportal sprints and new alignment actions. PM
2025-11-22 Added UI parity-matrix delivery action to keep data provider integration on track. PM
2025-11-24 Pinned generator toolchain (OpenAPI Generator CLI 7.4.0, JDK 21), template layout, and reproducibility rules; captured in src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md + toolchain.lock.yaml. SDK Generator Guild
2025-11-24 Started SDKGEN-62-002: added shared post-process scaffold (postprocess/), LF/whitespace normalizer script, and README for language hooks. SDK Generator Guild
2025-11-24 Completed SDKGEN-62-002: postprocess now copies auth/retry/pagination/telemetry helpers for TS/Python/Go/Java, wires TS/Python exports, and adds smoke tests. SDK Generator Guild
2025-11-24 Began SDKGEN-63-001: added TypeScript generator config (ts/config.yaml), deterministic driver script (ts/generate-ts.sh), and README; waiting on frozen OAS spec to produce alpha artifact. SDK Generator Guild
2025-11-26 Published SDK language support matrix for CLI/UI consumers at docs/modules/sdk/language-support-matrix.md; Action #2 closed. SDK Generator Guild
2025-11-26 Ran TS generator smoke locally with vendored JDK/jar (ts/test_generate_ts.sh); pass. Blocked until aggregate OpenAPI spec is frozen/published to generate Wave B alpha artifact. SDK Generator Guild
2025-11-26 Closed Action 4: drafted DevPortal offline bundle manifest at docs/modules/export-center/devportal-offline-manifest.md to align SDKREL-64-002 with SPRINT_0206. SDK Release Guild
2025-11-26 Added spec hash guard to TS/Python generators (STELLA_OAS_EXPECTED_SHA256) and emit .oas.sha256 for provenance; updated smoke tests and READMEs. SDK Generator Guild
2025-11-26 Scaffolded Go generator (config/script/smoke), enabled hash guard + helper copy via postprocess, and added .oas.sha256 emission; waiting on frozen OAS for Wave B alpha. SDK Generator Guild
2025-11-26 Scaffolded Java generator (config/script/smoke), added postprocess hook copy into org.stellaops.sdk, hash guard + .oas.sha256, and vendored-JDK fallback; waiting on frozen OAS for Wave B alpha. SDK Generator Guild
2025-11-26 Marked SDKGEN-63-003/004 BLOCKED pending frozen aggregate OAS digest; scaffolds and smoke tests are ready. SDK Generator Guild
2025-11-26 Added unified SDK smoke npm scripts (sdk:smoke:*, sdk:smoke) covering TS/Python/Go/Java to keep pre-alpha checks consistent. SDK Generator Guild
2025-11-26 Added CI workflow .gitea/workflows/sdk-generator.yml to run npm run sdk:smoke on SDK generator changes (TS/Python/Go/Java). SDK Generator Guild
2025-11-27 Marked SDKGEN-63-001/002 BLOCKED pending frozen aggregate OAS digest; scaffolds and smokes remain ready. SDK Generator Guild
2025-11-30 Marked SDKGEN-64-001 and SDKGEN-64-002 BLOCKED pending Wave B (SDKGEN-63-004) OAS freeze/Java alpha; CLI/UI adoption cannot proceed without generated SDK artifacts. Project Mgmt
2025-11-30 Status audit: set SDKGEN-63-001..004 to BLOCKED per aggregate OAS freeze; flagged registry signing key action overdue; added OAS-freeze risk entry. PM
2025-11-30 Added Actions #6–#7 to chase aggregate OAS snapshot (APIG0101) and sovereign signing key provisioning by 2025-12-02. PM
2025-11-30 Set SDKREL-63-001..64-002 to BLOCKED pending signing keys and downstream artifacts; clarified blockers in Delivery Tracker. PM
2025-12-01 Sprint-wide pause: all Delivery Tracker items blocked on OAS snapshot + signing keys; Wave B checkpoints will slip if Actions #6–#7 miss 2025-12-02. PM
2025-11-24 Added fixture OpenAPI (ts/fixtures/ping.yaml) and smoke test (ts/test_generate_ts.sh) to validate TypeScript pipeline locally; skips if generator jar absent. SDK Generator Guild
2025-11-24 Vendored tools/openapi-generator-cli-7.4.0.jar and tools/jdk-21.0.1.tar.gz with SHA recorded in toolchain.lock.yaml; adjusted TS script to ensure helper copy post-run and verified generation against fixture. SDK Generator Guild
2025-11-24 Ran ts/test_generate_ts.sh with vendored JDK/JAR and fixture spec; smoke test passes (helpers present). SDK Generator Guild
2025-11-24 Added deterministic TS packaging templates (package.json, tsconfig base/cjs/esm, README, sdk-error) copied via postprocess; updated helper exports and lock hash. SDK Generator Guild
2025-11-24 Began SDKGEN-63-002: added Python generator config/script/README + smoke test (reuses ping fixture); awaiting frozen OAS to emit alpha. SDK Generator Guild
2025-11-27 Began SDKGEN-63-003: added Go SDK generator scaffold with config (go/config.yaml), driver script (go/generate-go.sh), smoke test (go/test_generate_go.sh), and README; context-first API design documented; awaiting frozen OAS to generate alpha. SDK Generator Guild
2025-11-27 Began SDKGEN-63-004: added Java SDK generator scaffold with config (java/config.yaml), driver script (java/generate-java.sh), smoke test (java/test_generate_java.sh), and README; OkHttp + Gson selected as HTTP client/serialization; builder pattern documented; awaiting frozen OAS to generate alpha. SDK Generator Guild