Smart configuration loader
expand layering prompt
+128
-4
+128
-4
layering.md
+128
-4
layering.md
···
1
-
# initial prompt
1
+
# c12-layer: Understanding & Extending c12's Configuration Layering
2
+
3
+
## Goals
4
+
5
+
This document guides analysis of c12's configuration layering system and proposes enhancements for more dynamic, introspectable configuration management.
6
+
7
+
## Part 1: Understanding the Current System
8
+
9
+
### Questions to Answer
10
+
11
+
1. **Where does layering happen?**
12
+
- How does `defu` merge configurations?
13
+
- What is the call graph from `loadConfig()` to final merged config?
14
+
15
+
2. **When in the lifecycle?**
16
+
- Map the complete execution pipeline from `loadConfig()` invocation to resolved config
17
+
- Identify when each source is loaded, when extends are resolved, when merging occurs
2
18
3
-
we want to understand how configuration from various sources is layered together. supposedly `defu` is used to merge configs. where does this happen? when in the lifecycle of execution happens? what is the total execution pipeline for a normal run of c12? use mermaid diagrams .
19
+
3. **What is the layer resolution order?**
20
+
- Document the priority stack (per README: overrides → config file → RC → global RC → package.json → defaults → extended layers)
21
+
- How does environment-specific config (`$development`, `$production`, etc.) factor in?
4
22
5
-
we want to try to understand more about how we might have more dynamic sources rather than a fixed path of sources. for instance we might want to make drop in config directories, such as talked about in https://github.com/unjs/c12/issues/298 .
23
+
### Deliverables
6
24
7
-
talking about how configuration becomes sourced. talk about how we can create a better registry of layers we are using. a registry of config layers, that can be built, and then ran, rather than a fixed pipeline. this project needs a more structured management of configuration, rather than being merely a fixed purpose tool.
25
+
- **Mermaid sequence diagram**: Show the lifecycle from `loadConfig()` call through to final config
26
+
- **Mermaid flowchart**: Show decision points (does RC exist? does config extend? etc.)
27
+
- **Code citations**: Link to the actual source locations where merging happens
28
+
29
+
---
30
+
31
+
## Part 2: Dynamic Configuration Sources
32
+
33
+
### Problem Statement
34
+
35
+
c12 currently has a fixed resolution pipeline. We want to explore:
36
+
37
+
1. **Drop-in config directories** (à la systemd's `*.conf.d/`)
38
+
- Reference: https://github.com/unjs/c12/issues/298
39
+
- Allow `<name>.config.d/` directories where multiple configs can be dropped in
40
+
- Configs sorted alphabetically (or with numeric prefixes like `00-base.ts`, `10-overrides.ts`)
41
+
42
+
2. **Pluggable source providers**
43
+
- Instead of hardcoded sources (file, RC, package.json), allow registering custom providers
44
+
- Examples: environment variables provider, remote config provider, vault/secrets provider
45
+
46
+
### Design Questions
47
+
48
+
- How would drop-in directories integrate with the existing layer system?
49
+
- Should drop-in configs be siblings to extended layers, or a separate concept?
50
+
- How do we handle ordering/priority for drop-in files?
51
+
52
+
---
53
+
54
+
## Part 3: Layer Registry Architecture
55
+
56
+
### Vision
57
+
58
+
Transform c12 from a "fixed pipeline config loader" into a "structured config layer manager" with:
59
+
60
+
1. **Explicit layer registry**
61
+
- Named, ordered collection of configuration sources
62
+
- Each layer has metadata: name, source type, priority, file path(s)
63
+
64
+
2. **Two-phase execution**
65
+
- **Build phase**: Construct the layer registry, validate sources exist, resolve extends
66
+
- **Run phase**: Execute the registry to produce final merged config
67
+
68
+
3. **Introspection capabilities**
69
+
- Query which layer provided a specific config key
70
+
- Trace config value provenance (like Rust's `figment` crate metadata)
71
+
- Debug mode showing layer-by-layer merge steps
72
+
73
+
### Inspiration
74
+
75
+
- **Rust's figment**: Providers with metadata, value provenance tracking
76
+
- **systemd**: Drop-in directories, clear override semantics
77
+
- **Kubernetes**: ConfigMap layering, strategic merge patches
78
+
79
+
### Proposed API Sketch
80
+
81
+
```typescript
82
+
// Build a layer registry explicitly
83
+
const registry = createLayerRegistry({
84
+
name: "myapp"
85
+
})
86
+
.addSource("defaults", { type: "static", config: { ... } })
87
+
.addSource("base-file", { type: "file", path: "myapp.config.ts" })
88
+
.addSource("drop-ins", { type: "directory", path: "myapp.config.d/" })
89
+
.addSource("env-overrides", { type: "env", prefix: "MYAPP_" })
90
+
.addSource("cli-overrides", { type: "static", config: cliArgs });
91
+
92
+
// Inspect before running
93
+
console.log(registry.layers); // See all registered sources
94
+
console.log(registry.resolve("database.host")); // Which layer provides this?
95
+
96
+
// Execute to get final config
97
+
const { config, provenance } = await registry.load();
98
+
```
99
+
100
+
---
101
+
102
+
## Part 4: Implementation Considerations
103
+
104
+
### Backward Compatibility
105
+
106
+
- `loadConfig()` should continue working unchanged
107
+
- New APIs are opt-in enhancements
108
+
109
+
### Key Extension Points to Identify
110
+
111
+
1. Where can we hook into layer resolution?
112
+
2. Can we intercept/wrap the merge function?
113
+
3. How do we inject additional sources into the pipeline?
114
+
115
+
### Files to Analyze
116
+
117
+
- `src/loader.ts` - Main loading logic
118
+
- `src/config.ts` - Config resolution
119
+
- Look for `defu` usage patterns
120
+
- Look for `extends` resolution logic
121
+
122
+
---
123
+
124
+
## Success Criteria
125
+
126
+
After this analysis, we should have:
127
+
128
+
1. Clear understanding of c12's internals with diagrams
129
+
2. Feasibility assessment for drop-in directories
130
+
3. Draft design for layer registry architecture
131
+
4. Identified extension points or required changes to c12