83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
<!-- file: crates/ksp-config-lib/README.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# ksp-config-lib
|
|
|
|
`ksp-config-lib` est le propriétaire unique de la configuration applicative KSP.
|
|
|
|
La crate centralise les documents JSON, leurs schemas, les profils et compositions, les variables d'environnement `KSP_*` / `KSPB_*`, le fichier `.env`, la résolution effective et les mutations persistantes explicitement autorisées.
|
|
|
|
## Responsabilités
|
|
|
|
`ksp-config-lib` possède :
|
|
|
|
- le bootstrap non récursif `config/` / `config/schemas/` et les overrides `--cfgpath` / `--schemapath` ;
|
|
- le registre logique `file_id -> filename` et les overrides `--filemap=<file_id>=<filename>` ;
|
|
- la lecture JSON et la validation JSON Schema Draft 2020-12 ;
|
|
- les invariants sémantiques KSP des documents connus ;
|
|
- les globals, `default_profile`, profils nommés et leur provenance ;
|
|
- les compositions génériques par `file_id`, sans dépendance à un filename physique ;
|
|
- le snapshot des variables process KSP/KSPB et la lecture de `./.env` ;
|
|
- la priorité `process > .env > fallback > missing` ;
|
|
- les placeholders `${NAME}` et `${NAME:-fallback}` ;
|
|
- la classification `Public`, `Internal`, `Secret` ;
|
|
- les représentations réelle et sûre/redacted ainsi que la provenance des valeurs résolues ;
|
|
- l'adapter du document Logging effectif vers `ksp_logging_lib::LoggingSettings` ;
|
|
- la surface de management pour inspecter les sources, modifier `std.logging.json`, consulter les rapports d'environnement, révéler explicitement une valeur réelle et modifier `.env` ;
|
|
- les écritures atomiques JSON/`.env` et la protection des permissions `.env` ;
|
|
- les audits workspace empêchant les bypass d'ownership Config et les oublis dans `.env.example`.
|
|
|
|
## Ressources gérées dans `0.1.3`
|
|
|
|
Le registre par défaut connaît :
|
|
|
|
```text
|
|
cfg.std.logging -> config/std.logging.json
|
|
schema.std.logging -> config/schemas/std.logging.schema.json
|
|
schema.composite -> config/schemas/composite.schema.json
|
|
```
|
|
|
|
`config/examples/composite.example.json` démontre le format composite sans créer de composite runtime fictif.
|
|
|
|
Le fichier local d'environnement est :
|
|
|
|
```text
|
|
./.env
|
|
```
|
|
|
|
Il n'est ni versionné ni livré. Le dépôt maintient `/.env.example` comme inventaire versionné des variables runtime utilisées. Toute nouvelle variable KSP/KSPB concrète doit y être ajoutée avec un commentaire d'usage dans le même delta que sa première utilisation.
|
|
|
|
## Frontières
|
|
|
|
Les autres crates et applications KSP ne doivent pas :
|
|
|
|
- lire directement les variables applicatives `KSP_*` / `KSPB_*` ;
|
|
- parser ou écrire directement `.env` ;
|
|
- ouvrir directement les documents Config connus par leur filename physique ;
|
|
- réimplémenter la sélection de profils, les compositions ou les placeholders ;
|
|
- reconstruire elles-mêmes la configuration Logging depuis le JSON.
|
|
|
|
`ksp-config-lib` dépend de `ksp-core-lib` pour `Error`/`Result` et de `ksp-logging-lib` pour les événements Config utiles et le contrat `LoggingSettings`.
|
|
|
|
La dépendance inverse est interdite : `ksp-core-lib` et `ksp-logging-lib` ne dépendent pas de Config.
|
|
|
|
Config ne possède pas le `LoggingGuard`. L'application ou le service qui orchestre le runtime construit la configuration effective puis possède le lifecycle `ksp_logging_lib::initialize/reinitialize`.
|
|
|
|
Tauri et les DTO TS-RS restent hors de cette crate. La future `ksp-app-config-desk` doit rester une frontière applicative mince au-dessus des APIs Config.
|
|
|
|
## Secrets
|
|
|
|
Un secret reste accessible au runtime ou au management lorsqu'un consumer autorisé en a réellement besoin, mais les vues ordinaires utilisent la représentation sûre.
|
|
|
|
Les méthodes `reveal_*` constituent un opt-in explicite au réel. L'authentification/autorisation de l'utilisateur humain appartient à l'application appelante et les valeurs retournées par ces méthodes ne doivent jamais être journalisées.
|
|
|
|
Le document Logging refuse les valeurs de sensibilité `Secret` dans sa configuration effective.
|
|
|
|
## Documentation
|
|
|
|
- [`USAGE.md`](USAGE.md) — construction du moteur, résolution runtime et management ;
|
|
- [`TODO.md`](TODO.md) — points explicitement différés après `0.1.3` ;
|
|
- [`../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan historique détaillé de la fondation Config ;
|
|
- [`../../config/std.logging.json`](../../config/std.logging.json) — premier document standard concret ;
|
|
- [`../../.env.example`](../../.env.example) — inventaire versionné des variables d'environnement runtime.
|