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, son inventaire public read-only ordonné par file_id 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 et réparer les sources Config enregistrées, 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

Le registre par défaut connaît :

cfg.std.logging    -> config/std.logging.json
schema.std.logging -> config/schemas/std.logging.schema.json
schema.composite   -> config/schemas/composite.schema.json

ConfigFileRegistry::descriptors() expose ces descripteurs en lecture seule et dans un ordre déterministe par file_id. Une application de management peut ainsi découvrir les fichiers connus sans maintenir une liste parallèle ni dépendre de leurs filenames physiques.

ConfigManagement::read_source() permet d'inspecter le texte brut d'un document Config enregistré même lorsque ce document est invalide. save_source_candidate() complète cette frontière : le candidat brut est parsé, validé contre son schema et les invariants sémantiques KSP, puis persisté atomiquement uniquement après validation complète. Le file_id doit appartenir au registre et désigner un document Config ; aucun path arbitraire n'est accepté.

config/examples/composite.example.json démontre le format composite sans créer de composite runtime fictif.

Le fichier local d'environnement est :

./.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 — construction du moteur, résolution runtime et management ;
TODO.md — points explicitement différés après 0.1.3 ;
../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md — plan historique détaillé de la fondation Config ;
../../config/std.logging.json — premier document standard concret ;
../../.env.example — inventaire versionné des variables d'environnement runtime.

5.3 KiB Raw Blame History