@zio.dev/zio-blocks 0.0.32 → 0.0.51

package/plans/config-follow-up-prs.md

@@ -0,0 +1,188 @@
+# Config Follow-up PR Plan
+
+This document turns the config assessment roadmap into concrete follow-up PR/issue-sized work items.
+
+---
+
+## PR 1 — Config Source Ecosystem and Secret File Ergonomics
+
+### Working title
+
+`feat(config): add env, secrets-dir, and _FILE config sources`
+
+### Goal
+
+Expand the source ecosystem so the config module is usable in real deployment environments without custom glue.
+
+### Scope
+
+- Add `ConfigSource.fromEnv(...)`
+- Make the system-properties source a clearly documented canonical public entrypoint
+- Add `ConfigSource.fromSecretsDir(...)`
+- Add `_FILE` convention support for file-backed secret indirection
+- Preserve provenance through all of the above
+- Keep default secret reporting redacted
+
+### Acceptance criteria
+
+- environment variables can be loaded as a first-class `ConfigSource`
+- a secrets directory can be loaded as a first-class `ConfigSource`
+- `_FILE` indirection works for secret-like values
+- precedence and composition are documented with examples
+- path traversal / invalid file cases are tested
+- provenance identifies real source keys without leaking secret values
+
+### Non-goals
+
+- Vault / cloud secret manager integration
+- hot reload
+- profiles / environments
+
+### Why it matters
+
+This closes the largest practical gap against Pydantic Settings, Spring Boot, Dynaconf, and koanf.
+
+---
+
+## PR 2 — Config Diagnostics and Explainability
+
+### Working title
+
+`feat(config): add explain/report APIs for resolved config and failures`
+
+### Goal
+
+Turn provenance into a true operator-facing differentiator.
+
+### Scope
+
+- Add a config explanation/report API
+- Improve human-readable load failure reports
+- Add machine-readable structured diagnostics
+- Explain why a value won when multiple sources are composed
+- Ensure secrets stay redacted throughout reports
+
+### Acceptance criteria
+
+- there is a first-class API for explaining resolved config
+- there is a first-class API for explaining load failure details
+- reports include source/key precedence information
+- reports are safe by default for secrets
+- docs include examples of using diagnostics in startup and tests
+
+### Non-goals
+
+- HTTP/Actuator endpoints
+- framework runtime integration
+
+### Why it matters
+
+This is the path to leapfrogging most libraries on debuggability, especially outside Spring and Figment.
+
+---
+
+## PR 3 — Profiles, Environments, and Layered Composition
+
+### Working title
+
+`feat(config): add profile-aware layered config composition`
+
+### Goal
+
+Support real deployment models (local/dev/staging/prod/test) without custom source wiring in every application.
+
+### Scope
+
+- Add a profile/environment concept
+- Add layered source helpers
+- Document deterministic precedence rules
+- Support test/dev/prod examples in docs
+
+### Acceptance criteria
+
+- applications can express a layered source model declaratively
+- precedence is deterministic and documented
+- examples cover local, CI, and production usage
+- tests cover cross-source override behavior
+
+### Non-goals
+
+- remote config systems
+- secret managers
+- live reload
+
+### Why it matters
+
+This closes one of the biggest operational gaps against Spring Boot, Dynaconf, and Figment.
+
+---
+
+## PR 4 — Secret Manager Integrations
+
+### Working title
+
+`feat(config): add secret manager source adapters`
+
+### Goal
+
+Support real production secret backends without forcing application-specific adapters.
+
+### Candidate integrations
+
+- Vault
+- AWS Secrets Manager
+- GCP Secret Manager
+- Azure Key Vault
+
+### Acceptance criteria
+
+- each integration composes as a `ConfigSource`
+- provenance identifies manager and secret key/version
+- secret values stay redacted by default
+- failure modes are explicit and tested
+
+### Why it matters
+
+This is where the library becomes truly production-native.
+
+---
+
+## PR 5 — Deprecation, Alias, and Migration Support
+
+### Working title
+
+`feat(config): support deprecated keys, aliases, and migration warnings`
+
+### Goal
+
+Make configuration evolution safe and user-friendly over time.
+
+### Scope
+
+- key aliases
+- deprecated key warnings
+- renamed key migration helpers
+- optional strict mode for rejecting deprecated keys
+
+### Acceptance criteria
+
+- old keys can be mapped to new keys
+- warnings are surfaced clearly
+- docs include migration examples
+- diagnostics explain alias/deprecation behavior
+
+### Why it matters
+
+This is a major usability feature for real framework adoption.
+
+---
+
+## Release sequencing recommendation
+
+1. PR 1 — source ecosystem + secret file ergonomics
+2. PR 2 — diagnostics and explainability
+3. PR 3 — profiles / environments / layered composition
+4. PR 5 — deprecation / alias support
+5. PR 4 — secret manager integrations
+
+This order maximizes immediate practical value while strengthening the long-term framework story.

package/plans/config-pr-assessment-roadmap.md

@@ -0,0 +1,310 @@
+# Config PR Assessment and Roadmap
+
+## Context
+
+This document captures the assessment of the current config PR (`feat(config): add config, config-yaml, config-json, config-hocon modules`) and the roadmap discussion for making the config system best-in-class.
+
+The core direction is strong:
+
+- typed configuration decoding from `Schema`
+- provenance tracking
+- unified config + flags + rollout model
+- DI integration via `Config.wire[...]`
+- synchronous, zero-dependency core
+
+But the PR is not yet best-in-class. The biggest gaps are documentation coherence, operational/source breadth, secret handling completeness, and introspection UX.
+
+---
+
+## Assessment Summary
+
+### Current strengths
+
+1. **Provenance is a real differentiator**
+   - `ConfigSource` and `FlagSource` carry source identity.
+   - resolved values retain provenance.
+   - composition preserves origin.
+   - this is genuinely better than many mainstream config libraries.
+
+2. **DI integration is unusually strong**
+   - `Config.wire[A]` and `Config.wire[A](prefix)` keep config decoding inside the dependency graph.
+   - this is framework-grade design rather than just “settings loading”.
+
+3. **Config + flags + rollout in one model**
+   - this is strategically smart and potentially differentiating.
+
+4. **Format adapters normalize into one model**
+   - YAML / JSON / HOCON all end up as `ConfigSource`, which keeps the rest of the system simple.
+
+### Current weaknesses
+
+1. **Public docs and API story are not fully coherent**
+   - stale `Option` docs where impl uses `Maybe`
+   - stale `Schema.derived` companion examples where Scala 3 `derives` is preferred
+   - generated README blocked by unrelated website-plugin failure
+
+2. **Source ecosystem is still narrow**
+   - no first-class secrets directory source
+   - no `_FILE` support
+   - no secret-manager integrations
+   - no clear profile/environment model
+
+3. **Secret handling is directionally correct but incomplete**
+   - `Secret` as string-only wrapper is good
+   - redaction exists, but full reporting/audit safety must be verified everywhere
+
+4. **Diagnostics are structured but not yet elite**
+   - errors are accumulated
+   - but “why did this value win?” / operator-facing explainability is still immature
+
+5. **Merge / precedence model is still basic**
+   - simple fallback composition works
+   - richer advanced composition semantics are still missing
+
+6. **Validation and operational governance are still shallow**
+   - strong decode
+   - weaker config-specific semantic validation, migration, deprecation, profile-aware rules
+
+---
+
+## Ecosystem Comparison
+
+### JVM / Spring Boot
+
+Spring Boot is ahead on:
+
+- property source ecosystem breadth
+- metadata generation
+- operational introspection (`env`, `configprops`, origin tracking)
+- mature profile model
+
+This PR is ahead on:
+
+- conceptual purity
+- tighter config/flags/rollout unification
+- stronger framework-substrate potential
+
+### Rust / Figment
+
+Figment is the closest conceptual peer.
+
+Figment is ahead on:
+
+- provider abstraction maturity
+- profile support
+- provider ecosystem
+- provenance polish
+
+This PR is ahead on:
+
+- DI integration
+- flag/rollout unification
+
+### Go / koanf
+
+koanf is ahead on:
+
+- provider breadth
+- composable source ecosystem
+- merge flexibility
+
+This PR is ahead on:
+
+- typed decode from schemas
+- provenance richness
+- DI integration
+
+### Python / pydantic-settings + dynaconf
+
+Pydantic settings is ahead on:
+
+- startup UX
+- strong validation ergonomics
+- nested env conventions
+- secrets dir support
+
+Dynaconf is ahead on:
+
+- layered source breadth
+- environment/profile support
+- secrets/provider integration
+
+This PR is ahead on:
+
+- provenance quality
+- DI alignment
+- config/flags/rollout unification
+
+### TypeScript / t3-env / envalid / convict
+
+These are ahead on:
+
+- startup validation ergonomics
+- low-friction adoption
+- concise developer experience
+
+This PR is ahead on:
+
+- hierarchical typed decode
+- provenance
+- multi-format config normalization
+- DI integration
+
+---
+
+## Roadmap
+
+### 1. Must merge now
+
+These are quality-bar issues for this PR itself.
+
+#### A. Fix public coherence
+
+- update `docs/reference/config.md` to `Maybe` instead of `Option`
+- update `Config.scala` Scaladoc examples to Scala 3 `derives Schema, Unscoped`
+- ensure all high-level examples use:
+  - `Config.wire[...]`
+  - `Resource.use(...)`
+  - Scala 3 style
+- either:
+  - fix `generateReadme`, or
+  - explicitly mark README generation as blocked by unrelated website-plugin failure in PR notes
+
+#### B. Tighten the config story
+
+Document the canonical golden path:
+
+```scala
+Wire(source)
+Config.wire[FooConfig]("foo")
+Resource.from[App](...)
+appResource.use(_.run())
+```
+
+#### C. Tighten secret guarantees
+
+Before merge, verify:
+
+- all human-facing config rendering redacts `Secret`
+- provenance never leaks secret raw values in default reporting
+- error formatting does not accidentally print secrets
+
+---
+
+### 2. Next 3 PRs
+
+#### PR 1 — Source ecosystem + secrets ergonomics
+
+Add:
+
+- `ConfigSource.fromEnv(...)`
+- `ConfigSource.fromSystemProperties(...)` as a clearly canonical public path
+- `ConfigSource.fromSecretsDir(...)`
+- `_FILE` convention support
+
+#### PR 2 — Diagnostics and explainability
+
+Add:
+
+- richer config load reports
+- “why did this value win?” APIs
+- structured diagnostic output
+- provenance rendering designed for operators
+
+#### PR 3 — Profiles / environments / layered config model
+
+Add:
+
+- named environments/profiles
+- explicit precedence helpers
+- layered composition utilities
+
+---
+
+### 3. 1.0 checklist
+
+For a true 1.0-quality config system:
+
+#### Core
+
+- typed decode from `Schema`
+- `Maybe`-based source API
+- provenance for every resolved value
+- config + flags + rollout unified
+- DI-first wiring
+- ergonomic `Resource.use(...)`
+
+#### Sources
+
+- map
+- env
+- system properties
+- YAML
+- JSON
+- HOCON
+- secrets dir
+- `_FILE`
+- custom source extension point
+
+#### Secrets
+
+- string-only `Secret`
+- default redaction everywhere
+- no accidental secret exposure in reports
+- nested secret support
+- secret manager adapter strategy
+
+#### Diagnostics
+
+- accumulated errors
+- explain/report API
+- effective-value provenance
+- machine-readable diagnostics
+- human-readable startup report
+
+#### Framework readiness
+
+- profile/environment model
+- clear precedence semantics
+- deprecation/migration support for renamed keys
+- test-friendly override model
+- future hook points for framework introspection
+
+---
+
+## Strategic Recommendation
+
+The product should be positioned as:
+
+> typed configuration with provenance, rollout, and DI integration
+
+not merely as another config library.
+
+The best path is to make the strongest differentiators impossible to miss:
+
+1. typed config that explains itself
+2. config that belongs inside the DI/runtime model
+3. one unified system for config, flags, and rollout
+
+---
+
+## Priority Order
+
+### Highest priority
+
+1. docs coherence
+2. secrets-dir + `_FILE`
+3. diagnostics / explainability
+
+### Medium priority
+
+4. profiles / environments
+5. custom source/provider story
+6. deprecation / alias migration support
+
+### Later
+
+7. secret manager integrations
+8. reload/watch model
+9. metadata/schema export
+10. framework actuator/introspection layer