macalbert/envilder/sdk-implementation-guide

SDK Implementation Guide

Step-by-step guide for building a new Envilder runtime SDK. Complements ADR-0003 (architecture pattern) and ADR-0005 (integration tiers). For website wiring and publishing, see the sdk-release-checklist skill.

When to Use

• Implementing a new runtime SDK (Go, Java, PHP, Rust, etc.)
• Reviewing an SDK PR for pattern compliance
• Onboarding a contributor to SDK development

Prerequisites

Before starting, read:

• ADR-0003: SDK Architecture Pattern
• ADR-0005: SDK Integration Tiers

1. Folder Structure

src/sdks/{runtime}/
├── domain/
│   ├── ISecretProvider          ← Port interface/protocol
│   ├── MapFileConfig            ← Config parsed from $config
│   ├── EnvilderOptions          ← Runtime overrides
│   ├── ParsedMapFile            ← Config + variable mappings
│   └── SecretProviderType       ← Enum (aws, azure)
├── application/
│   ├── Envilder                 ← Public facade (Tier 1 + Tier 2)
│   ├── EnvilderClient           ← Core resolver
│   ├── MapFileParser            ← JSON parsing logic
│   └── SecretValidation         ← Opt-in validate function
├── infrastructure/
│   ├── SecretProviderFactory    ← Internal, not exported
│   ├── aws/
│   │   └── AwsSsmSecretProvider
│   └── azure/
│       └── AzureKeyVaultSecretProvider
└── integrations/                ← Tier 3 (future, community-driven)
    └── {framework}/

Tests mirror the structure under tests/sdks/{runtime}/.

Note: This is the logical structure. Each runtime adapts to its own

conventions (e.g., Node.js uses src/ subfolder, Python uses package name

as root directory).

2. Mandatory API Surface

Tier 1: Static Facade (one-liner)

Envilder.load("map.json")              → injects into process env
Envilder.resolveFile("map.json")       → returns resolved key-value pairs

Tier 2: Fluent Builder

Envilder.fromMapFile("map.json")
  .withProvider("azure")
  .withVaultUrl("https://vault.azure.net")
  .withProfile("my-profile")           // AWS only
  .inject()                            // injects into env
  // OR
  .resolve()                           // returns key-value pairs

Environment Routing (both tiers)

Envilder.load("production", {
  "production": "prod-map.json",
  "staging": "stg-map.json"
})

3. Provider Contract

Sync vs Async per Runtime

Batch vs Individual

4. Internal vs Public Separation

The SecretProviderFactory is always internal (not part of public API):

5. Naming Conventions

Package/Module Names

Class/Struct Naming

• Facade class is always Envilder (consistent cross-SDK brand)
• Client class is always EnvilderClient
• Provider interface: ISecretProvider (or language equivalent: Protocol, trait, interface)

6. Vanity Imports (Go)

Go module path is envilder.com/go. This requires a vanity import HTML at https://envilder.com/go?go-get=1:

<meta name="go-import" content="envilder.com/go git https://github.com/macalbert/envilder">
<meta name="go-source" content="envilder.com/go https://github.com/macalbert/envilder https://github.com/macalbert/envilder/tree/main/src/sdks/go{/dir} https://github.com/macalbert/envilder/tree/main/src/sdks/go{/dir}/{file}#L{line}">

Serve from the Envilder website (src/website/public/go/index.html).

7. Testing Skeleton

Every SDK must have:

• [ ] Unit tests for MapFileParser
• [ ] Unit tests for EnvilderClient (mock ISecretProvider)
• [ ] Unit tests for Envilder facade (mock client/provider)
• [ ] Unit tests for SecretValidation
• [ ] Unit tests for cross-provider validation
• [ ] Acceptance tests with LocalStack (AWS SSM)
• [ ] Acceptance tests with LocalStack for Azure (Azure Key Vault)

Follow sdk-acceptance-testing skill for container wrapper patterns.

8. Implementation Order (per SDK)

1. Domain types (MapFileConfig, EnvilderOptions, SecretProviderType, ISecretProvider)
2. MapFileParser + tests
3. EnvilderClient + tests
4. AwsSsmSecretProvider + acceptance tests
5. AzureKeyVaultSecretProvider + acceptance tests
6. Envilder facade (Tier 1 + Tier 2) + tests
7. SecretValidation + tests
8. Cross-provider validation + tests
9. README, changelog, website wiring (→ sdk-release-checklist skill)

9. Checklist Before Submitting PR

• [ ] All unit tests pass
• [ ] All acceptance tests pass (Docker required)
• [ ] SecretProviderFactory is not publicly exported
• [ ] Tier 1 (load) and Tier 2 (fromMapFile().inject()) work end-to-end
• [ ] Missing secrets silently omitted (no exceptions from provider)
• [ ] validateSecrets() throws on empty/missing values
• [ ] Cross-provider errors: profile+Azure→error, vaultUrl+AWS→error
• [ ] Options override $config values
• [ ] Environment routing works
• [ ] Follows language-idiomatic conventions (naming, async model, visibility)