Code cleanup

GEMINI.md

@@ -13,24 +13,30 @@ This document serves as the internal developer guide for `kcd`. It explains the
 
 ### Core Modules
 
--   `src/client.rs`: Low-level wrapper for the Keycloak Admin REST API. Handles authentication (Token/Password/Client Credentials) and HTTP requests using `reqwest`.
--   `src/models.rs`: Serde-based representations of Keycloak resources. We use `#[serde(flatten)]` with a `HashMap<String, Value>` to maintain forward/backward compatibility with unknown Keycloak fields.
--   `src/inspect.rs`: Deep-scans the remote Keycloak server and serializes resources into local files.
+-   `src/client.rs`: Low-level wrapper for the Keycloak Admin REST API. Handles authentication and provides a **generic CRUD interface** for Keycloak resources.
+-   `src/models.rs`: Serde-based representations of Keycloak resources. Defines the `KeycloakResource` and `ResourceMeta` traits for generic resource management.
+-   `src/inspect.rs`: Deep-scans the remote Keycloak server and serializes resources into local files using a **generic, parallelized inspection pipeline**.
 -   `src/utils/secrets.rs`: Uses heuristics to find and mask sensitive fields in configuration objects.
+-   `src/utils/ui.rs`: Centralized module for CLI output formatting and emoji management.
+-   `src/clean.rs`: Removes local workspace representations of Keycloak realms and resources using **parallel I/O**.
+-   `src/validate.rs`: Performs local validation of YAML configurations before they are applied using **async I/O**.
+-   `src/cli.rs`: Command-line interface definitions and logic for scaffolding new resources.
 
 ---
 
 ## 🛠️ Adding a New Resource Support
 
 To support a new Keycloak resource (e.g., "Event Listeners"):
 
-1.  **Update `models.rs`**: Add the `struct` for the resource and register it in the corresponding realm or parent resource.
-2.  **Update `client.rs`**: Add CRUD methods for the new resource.
-3.  **Update `inspect.rs`**: Add a function to fetch and save the resource to disk.
-4.  **Update `plan.rs`**: Logic to compare the local and remote versions of the resource.
-5.  **Update `apply.rs`**: Hook the resource into the reconciliation loop.
-6.  **Update `validate.rs`**: (Optional) Add specific validation rules.
-7.  **Update `cli.rs`**: (Optional) Add interactive scaffolding for the new resource.
+1.  **Update `models.rs`**: 
+    - Add the `struct` for the resource.
+    - Implement `KeycloakResource` (for name/ID handling).
+    - Implement `ResourceMeta` (to define API paths, directory names, and secret prefixes).
+2.  **Update `inspect.rs`**: Add a `spawn_inspect::<NewResourceRepresentation>(...)` call in the `inspect_realm` function.
+3.  **Update `plan.rs`**: Logic to compare the local and remote versions of the resource.
+4.  **Update `apply.rs`**: Hook the resource into the reconciliation loop.
+5.  **Update `validate.rs`**: (Optional) Add specific validation rules.
+6.  **Update `cli.rs`**: (Optional) Add interactive scaffolding for the new resource.
 
 ---
 
@@ -67,16 +73,19 @@ When detected, the value is replaced by `${KEYCLOAK_<RESOURCE_TYPE>_<RESOURCE_NA
 ## 📜 Coding Conventions
 
 1.  **Asynchronous by Default**: All I/O and API operations must use `tokio`.
-2.  **Error Handling**: Use `anyhow::Context` for descriptive error chains.
-3.  **Formatting**: Run `cargo fmt` before every commit.
-4.  **Clippy**: Ensure `cargo clippy` passes without warnings.
-5.  **Serialization**: Prefer `serde_yaml_ng` for YAML operations to ensure compatibility with modern YAML features.
+2.  **Concurrency**: Use `tokio::task::JoinSet` to parallelize independent resource operations (e.g., fetching multiple clients).
+3.  **Generic Abstractions**: Prefer using the generic CRUD methods in `KeycloakClient` and the `KeycloakResource`/`ResourceMeta` traits to avoid boilerplate.
+4.  **Error Handling**: Use `anyhow::Context` for descriptive error chains, including specific resource identifiers (e.g., realm name).
+5.  **Formatting**: Run `cargo fmt` before every commit.
+6.  **Clippy**: Ensure `cargo clippy` passes without warnings.
+7.  **Serialization**: Prefer `serde_yaml_ng` for YAML operations to ensure compatibility with modern YAML features.
 
 ---
 
 ## 🚀 Future Roadmap
 
+-   [x] Parallel reconciliation (apply changes concurrently for resources within a realm).
 -   [ ] Support for custom SPIs and provider configurations.
--   [ ] Parallel reconciliation (apply changes concurrently for different realms).
 -   [ ] Support for multiple environment profiles (e.g., `prod.yaml`, `staging.yaml`).
 -   [ ] Integration with HashiCorp Vault for secret resolution.
+-   [ ] Generic refactor for `plan.rs` and `apply.rs` (similar to `inspect.rs`).

README.md

@@ -7,7 +7,7 @@
 
 **Disclaimer**: This project is experimentally written almost entirely by AI, so any usage should keep this in mind and that the execution of this software is at your own risk.
 
-`kcd` is a robust CLI tool for the **declarative management** of Keycloak configurations. It allows you to treat your Keycloak settings as code, enabling version control, automated testing, and seamless continuous delivery of your identity infrastructure.
+`kcd` is a robust CLI tool for the **declarative management** of [Keycloak](https://www.keycloak.org/) configurations. It allows you to treat your Keycloak settings as code, enabling version control, automated testing, and seamless continuous delivery of your identity infrastructure.
 
 ---
 
@@ -55,6 +55,7 @@ $ kcd cli
 
 ## 🚀 Key Features
 
+- **Blazing Fast Performance**: Utilizes Rust's `tokio` for highly concurrent API interactions and parallel I/O operations.
 - **Declarative State**: Define your desired Keycloak state in human-readable YAML files.
 - **Inspect & Export**: Bootstrap your project by exporting existing Keycloak configurations to local files.
 - **Dry-Run Planning**: Preview exactly what changes will be applied before they happen.
@@ -212,6 +213,12 @@ This format provides an immediate understanding of how recent your installed ver
 
 ---
 
+## 🤝 Credits
+
+`kcd` is built for and relies on the excellent work of the [Keycloak](https://www.keycloak.org/) project and its community. Keycloak is an open-source identity and access management solution.
+
+---
+
 ## 📄 License
 
 Distributed under the MIT License. See `LICENSE` for more information.