<!-- file: ks-config/USAGE.md -->
<!-- version: 7 -->

# Utilisation de ks-config

## Chargement recommandé

```rust
let config_result = ks_config::read_config_json_file_with_environment(
    std::path::Path::new("config/app.config.json"),
    std::path::Path::new("."),
);
let config = match config_result {
    Ok(value) => value,
    Err(error) => return Err(error),
};
let profile = match ks_config::active_profile(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
```

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

```rust
let report = match ks_config::load_workspace_environment(std::path::Path::new(".")) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

if let Some(path) = report.loaded_path {
    println!("environment file: {}", path.display());
}
```

`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/ks}"}"#;
let resolved = ks_config::resolve_environment_placeholders(raw);

assert!(resolved.contains("databaseUrl"));
```

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

```rust
if let Err(error) = ks_config::validate_config_json_schema(raw_json) {
    return Err(error);
}
let config = match ks_config::parse_config_json(raw_json) {
    Ok(value) => value,
    Err(error) => return Err(error),
};
if let Err(error) = ks_config::validate_config(&config) {
    return Err(error);
}
```

`parse_config_json` effectue déjà les deux validations ; les appels séparés servent aux outils de diagnostic.

## Schéma embarqué

```rust
let schema_text = ks_config::config_json_schema_text();
let schema_value = match ks_config::config_json_schema_value() {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("embedded app schema bytes={}", schema_text.len());
assert!(schema_value.is_object());
```

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

```rust
let profile = match ks_config::active_profile(&config) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("active profile: {}", profile.name);
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 ;
- `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 et les contraintes wallet.

## Tests instructifs

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 ;
- aucune connexion externe n’est ouverte par la crate ;
- la politique de camouflage des valeurs résolues appartient à `0.5.1-pre.006`.