0.5.1-pre.005

ks-config/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: ks-config/USAGE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Utilisation de ks-config
 
@@ -7,7 +7,7 @@
 
 ```rust
 let config_result = ks_config::read_config_json_file_with_environment(
-    std::path::Path::new("config/example.config.json"),
+    std::path::Path::new("config/app.config.json"),
     std::path::Path::new("."),
 );
 let config = match config_result {
@@ -20,7 +20,9 @@ let profile = match ks_config::active_profile(&config) {
 };
 ```
 
-Cette fonction charge l’environnement du workspace, résout les placeholders puis applique successivement le schéma JSON, la désérialisation typée et les invariants métier.
+Cette API charge l’environnement du workspace, résout les placeholders puis applique successivement le schéma JSON général, la désérialisation typée et les invariants métier.
+
+Le fichier chargé par défaut par le desktop est `config/app.config.json`. `KS_CONFIG_PATH` permet de remplacer explicitement ce chemin.
 
 ## Chargement de l’environnement
 
@@ -35,18 +37,20 @@ if let Some(path) = report.loaded_path {
 }
 ```
 
-`EnvironmentLoadReport` indique le fichier chargé, s’il existe. Par défaut, `ks-config` sélectionne `.env`; `KS_ENV_FILE` permet de choisir explicitement un autre fichier sans écraser les variables déjà présentes dans le processus. Les placeholders non résolus sans fallback restent visibles afin que la validation ou le consommateur puisse les signaler explicitement. Les contrats d’environnement du workspace utilisent désormais `KS_*` pour Khadhroony Solana et `KB_*` pour les futurs besoins réellement propres au Bot.
+`EnvironmentLoadReport` indique le fichier chargé. Par défaut, `ks-config` sélectionne `.env`; `KS_ENV_FILE` permet d’en choisir un autre sans écraser les variables déjà présentes dans le processus.
+
+Les contrats d’environnement utilisent `KS_*` pour Khadhroony Solana et `KB_*` pour les besoins réellement propres au Bot.
 
 ## Résolution explicite des placeholders
 
 ```rust
-let raw = r#"{"databaseUrl":"${KS_SECRET_POSTGRES_DEVNET_URL:-postgres://localhost/kb}"}"#;
+let raw = r#"{"databaseUrl":"${KS_SECRET_POSTGRES_DEVNET_URL:-postgres://localhost/ks}"}"#;
 let resolved = ks_config::resolve_environment_placeholders(raw);
 
 assert!(resolved.contains("databaseUrl"));
 ```
 
-Cette API retourne actuellement une chaîne résolue ordinaire et peut donc contenir des secrets issus de l’environnement. Elle doit rester strictement backend et ne doit pas être utilisée pour afficher, logger ou transmettre le JSON résolu. `0.5.1` remplacera cette frontière par une résolution conservant la classification de sensibilité.
+Cette API retourne encore une chaîne ordinaire pouvant contenir des secrets résolus. Elle reste strictement backend jusqu’à l’introduction de la représentation sensible de `0.5.1-pre.006`.
 
 ## Validation et parsing
 
@@ -65,29 +69,6 @@ if let Err(error) = ks_config::validate_config(&config) {
 
 `parse_config_json` effectue déjà les deux validations ; les appels séparés servent aux outils de diagnostic.
 
-## Sérialisation
-
-```rust
-let compact = match ks_config::serialize_config_json(&config) {
-    Ok(value) => value,
-    Err(error) => return Err(error),
-};
-let pretty = match ks_config::serialize_config_json_pretty(&config) {
-    Ok(value) => value,
-    Err(error) => return Err(error),
-};
-
-let write_result = std::fs::write("config/generated.config.json", pretty);
-if let Err(error) = write_result {
-    return Err(ks_core::Error::new(
-        "config_write_failed",
-        format!("cannot write generated configuration: {error}"),
-    ));
-}
-```
-
-La configuration est validée avant sérialisation.
-
 ## Schéma embarqué
 
 ```rust
@@ -97,15 +78,11 @@ let schema_value = match ks_config::config_json_schema_value() {
     Err(error) => return Err(error),
 };
 
-let property_count = schema_value
-    .get("properties")
-    .and_then(serde_json::Value::as_object)
-    .map_or(0, serde_json::Map::len);
-
-println!("embedded schema bytes={}, properties={property_count}", schema_text.len());
+println!("embedded app schema bytes={}", schema_text.len());
+assert!(schema_value.is_object());
 ```
 
-Le schéma actif est aussi disponible sous [`../config/schema.config.json`](../config/schema.config.json). Le fichier [`../config/example.config.json`](../config/example.config.json) fournit un exemple utilisateur complet.
+Le schéma actif est [`../config/schemas/app.config.schema.json`](../config/schemas/app.config.schema.json). Les fichiers [`../config/app.config.json`](../config/app.config.json) et [`../config/example.app.config.json`](../config/example.app.config.json) doivent tous deux être conformes.
 
 ## Sélection du profil actif
 
@@ -120,24 +97,47 @@ println!("http endpoints: {}", profile.solana.http_endpoints.len());
 println!("websocket endpoints: {}", profile.solana.ws_endpoints.len());
 ```
 
+Le profil applicatif ne contient plus de configuration logging. Le document logging et son `active_profile` sont chargés par `ks-logging`.
+
+## Sérialisation
+
+```rust
+let pretty = match ks_config::serialize_config_json_pretty(&config) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+
+let write_result = std::fs::write("config/generated.app.config.json", pretty);
+if let Err(error) = write_result {
+    return Err(ks_core::Error::new(
+        "config_write_failed",
+        format!("cannot write generated configuration: {error}"),
+    ));
+}
+```
+
+La configuration est validée avant sérialisation.
+
 ## Types publics importants
 
 - `AppConfig`, `ProfileConfig`, `AppSectionConfig` ;
 - `DatabaseConfig`, `PostgresConfig`, `SqliteConfig`, `DataConfig` ;
 - `SolanaConfig`, `HttpEndpointConfig`, `WsEndpointConfig`, `EndpointRoleConfig` ;
 - `ListenerConfig` et ses variantes ;
-- `LoggingConfig`, `LogTargetConfig`, `LogTargetFilterConfig` ;
 - `WalletConfig`, `ExecutionConfig`, `DemoConfig`.
 
+Les types logging ne font plus partie de `ks-config`.
+
 ## Erreurs et invariants
 
-Les erreurs utilisent `ks_core::Error` avec un code stable. Les validations couvrent notamment l’unicité des profils, l’existence du profil actif, les URLs, les rôles d’endpoints, les limites d’exécution, les routes de logging et les contraintes wallet.
+Les erreurs utilisent `ks_core::Error` avec un code stable. Les validations couvrent notamment l’unicité des profils, l’existence du profil actif, les URLs, les rôles d’endpoints, les limites d’exécution et les contraintes wallet.
 
 ## Tests instructifs
 
-Les tests `example_config_validates_against_schema`, `example_config_parses_and_resolves_active_profile` et `example_config_routes_global_and_operational_crate_files` démontrent le contrat complet de l’exemple actif. Les tests `parser_rejects_*` et `schema_rejects_*` documentent les invariants refusés.
+Les tests vérifient séparément `app.config.json` et `example.app.config.json`, le roundtrip du document général et les invariants `parser_rejects_*` / `schema_rejects_*`.
 
 ## Limites
 
 - format JSON uniquement ;
-- la crate valide les références et paramètres, mais n’ouvre aucune connexion externe.
+- aucune connexion externe n’est ouverte par la crate ;
+- la politique de camouflage des valeurs résolues appartient à `0.5.1-pre.006`.