feat: allow cli to connect to a couchbase auditstore (#726)

Author: bercianor

cli/flamingock-cli/CLI-README.md

@@ -76,7 +76,7 @@ After building, `flamingock-cli-dist/` contains:
 - **`flamingock-cli.jar`** - Self-contained executable JAR with all dependencies
 - **`flamingock`** - Unix/Linux/macOS executable shell script
 - **`flamingock.bat`** - Windows executable batch file
-- **`flamingock.yml`** - Sample configuration file
+- **`flamingock-cli.yml`** - Sample configuration file
 
 ## Configuration
 
@@ -115,9 +115,22 @@ flamingock:
       # secret-key: "your-secret"          # Optional, uses AWS credential chain
 ```
 
+### Couchbase Example
+```yaml
+flamingock:
+  service-identifier: "flamingock-cli"
+  audit:
+    couchbase:
+      endpoint: "http://localhost:8000"
+      username: "your-username"
+      password: "your-password"
+      bucket-name: "test"
+      table: "flamingockAuditLog"           # Optional, defaults to "flamingockAuditLog"
+```
+
 ### Configuration File Resolution
 1. Command line argument: `--config /path/to/file.yml`
-2. Default: `flamingock.yml` in current directory
+2. Default: `flamingock-cli.yml` in bin directory
 
 ## Architecture
 
@@ -144,6 +157,7 @@ client.markAsRolledBack(changeId);
 ### Database Support
 - **MongoDB**: Uses MongoDB Sync driver (not Spring Data)
 - **DynamoDB**: Uses AWS SDK v2
+- **Couchbase**: Uses Couchbase driver v3.7.3
 - **Auto-detection**: Based on YAML configuration structure
 - **Validation**: Connection testing during client creation
 
@@ -179,12 +193,12 @@ Uses SLF4J with simple implementation for clean, professional output.
 ## Build System Integration
 
 ### Gradle Tasks
-| Task | Description |
-|------|-------------|
-| `:cli:flamingock-cli:build` | Full build with distribution |
-| `:cli:flamingock-cli:uberJar` | Create self-contained JAR only |
+| Task                                       | Description                      |
+|--------------------------------------------|----------------------------------|
+| `:cli:flamingock-cli:build`                | Full build with distribution     |
+| `:cli:flamingock-cli:uberJar`              | Create self-contained JAR only   |
 | `:cli:flamingock-cli:generateDistribution` | Generate executable scripts only |
-| `:cli:flamingock-cli:clean` | Remove all CLI artifacts |
+| `:cli:flamingock-cli:clean`                | Remove all CLI artifacts         |
 
 ### Automatic Distribution
 The build process automatically:

cli/flamingock-cli/CLI_SPECIFICATION.md

@@ -8,13 +8,13 @@ flamingock [command] [operation] [options]
 
 ## General Principles
 
-- The CLI is **lightweight**: 
-  - It only builds an `OpsClient` via the `OpsClientBuilder`. 
-  - All business logic is delegated to the `OpsClient` (or components it delegates to). 
+- The CLI is **lightweight**:
+  - It only builds an `OpsClient` via the `OpsClientBuilder`.
+  - All business logic is delegated to the `OpsClient` (or components it delegates to).
   - The CLI only parses input, calls `OpsClient`, and formats output.
-  
-- Default behavior: 
-  - `flamingock audit list` (with no flags) → shows the **current snapshot** (latest state per change). 
+
+- Default behavior:
+  - `flamingock audit list` (with no flags) → shows the **current snapshot** (latest state per change).
   - Flags modify or filter the behavior.
 
 ---
@@ -31,11 +31,11 @@ flamingock audit list
 ```
 
 **Options:**
-- `--issues` (boolean, no value) → only audits with issues 
-- `--history` (boolean, no value) → full chronological audit history (all states, ordered by time) 
-- `--since <date>` (string, ISO-8601, e.g. `2025-01-01T00:00:00`) → list audits since a given date 
-- `--limit <n>` (integer) → pagination limit 
-- `--page <n>` (integer) → pagination page 
+- `--issues` (boolean, no value) → only audits with issues
+- `--history` (boolean, no value) → full chronological audit history (all states, ordered by time)
+- `--since <date>` (string, ISO-8601, e.g. `2025-01-01T00:00:00`) → list audits since a given date
+- `--limit <n>` (integer) → pagination limit
+- `--page <n>` (integer) → pagination page
 
 **Examples:**
 ```bash
@@ -58,8 +58,8 @@ flamingock audit mark --change-unit <id> --state <state>
 ```
 
 **Options:**
-- `--change-unit <id>` / `-c <id>` → the changeId (required) 
-- `--state <state>` / `-s <state>` → the state to mark (`APPLIED` or `ROLLED_BACK`) (required) 
+- `--change-unit <id>` / `-c <id>` → the changeId (required)
+- `--state <state>` / `-s <state>` → the state to mark (`APPLIED` or `ROLLED_BACK`) (required)
 
 **Examples:**
 ```bash
@@ -71,7 +71,7 @@ flamingock audit mark -c CU123 -s ROLLED_BACK
 
 ## Global Options
 
-- `--config <file>` / `-c <file>` → path to configuration file (default: `flamingock.yml`)
+- `--config <file>` / `-c <file>` → path to configuration file (default: `flamingock-cli.yml`)
 - `--help` / `-h` → show help information
 - `--version` / `-V` → show version information
 
@@ -80,8 +80,8 @@ flamingock audit mark -c CU123 -s ROLLED_BACK
 ## Summary
 
 - Command structure: `flamingock [command] [operation] [options]`
-- For now, only the `audit` command is implemented with: 
-  - `list` (default snapshot, optional filters `--issues`, `--history`, `--since`, pagination) 
+- For now, only the `audit` command is implemented with:
+  - `list` (default snapshot, optional filters `--issues`, `--history`, `--since`, pagination)
   - `mark` (force a state for a change)
 - The CLI is a thin layer: config → build OpsClient → call → format result.
 
@@ -93,4 +93,4 @@ flamingock audit mark -c CU123 -s ROLLED_BACK
 - **History flag**: Use `--history` to get the full chronological audit history.
 - **Issues flag**: Use `--issues` to filter for only entries with problems.
 - **Since flag**: Use `--since` with ISO-8601 format to filter by date.
-- **Pagination**: Client-side pagination is supported with `--limit` and `--page` flags.
+- **Pagination**: Client-side pagination is supported with `--limit` and `--page` flags.

cli/flamingock-cli/DEVELOPMENT.md

@@ -213,7 +213,7 @@ curl http://localhost:8000/shell/
 **"Configuration file not found"**
 ```bash
 # Debug: Check working directory
-./gradlew :cli:flamingock-cli:debugCli --args="--config $PWD/flamingock-cli-dist/flamingock.yml audit list"
+./gradlew :cli:flamingock-cli:debugCli --args="--config $PWD/flamingock-cli-dist/flamingock-cli.yml audit list"
 ```
 
 **"Failed to create OpsClient"**
@@ -226,7 +226,7 @@ export JAVA_OPTS="-Dorg.mongodb.driver.level=DEBUG"
 **"Multiple database configurations"**
 ```bash
 # Validate YAML structure
-cat flamingock-cli-dist/flamingock.yml | grep -A5 "audit:"
+cat flamingock-cli-dist/flamingock-cli.yml | grep -A5 "audit:"
 ```
 
 #### Debug Log Analysis

cli/flamingock-cli/README.md

@@ -47,7 +47,7 @@ cd flamingock-java
    ```bash
    # Linux/macOS
    tar -xzf flamingock-cli-{version}.tar.gz
-   
+
    # Windows (or use any ZIP tool)
    unzip flamingock-cli-{version}.zip
    ```
@@ -56,7 +56,7 @@ cd flamingock-java
    ```bash
    # Linux/macOS
    ./flamingock-cli-{version}/bin/flamingock --help
-   
+
    # Windows
    flamingock-cli-{version}\bin\flamingock.bat --help
    ```
@@ -81,18 +81,18 @@ java -jar flamingock-cli.jar --help
 
 ## Configuration
 
-Create a `flamingock.yml` configuration file (see `flamingock-sample.yml` for reference):
+Modify `flamingock-cli.yml` configuration file:
 
 ```yaml
 flamingock:
   service-identifier: "my-service"
-  
+
   # For MongoDB
   audit:
     mongodb:
       connection-string: "mongodb://localhost:27017"
       database: "myapp"
-  
+
   # For DynamoDB
   # audit:
   #   dynamodb:
@@ -112,7 +112,7 @@ flamingock audit list                    # List all audit entries
 flamingock audit get -c <change-id>      # Get specific audit entry
 flamingock audit fix -c <change-id>      # Fix audit issue
 
-# Issue operations  
+# Issue operations
 flamingock issue list                    # List all issues
 flamingock issue get                     # Get next issue (or specific with -c)
 flamingock issue get -c <change-id>      # Get specific issue
@@ -206,7 +206,7 @@ cli/flamingock-cli/
 │   │   ├── config/                     # Configuration handling
 │   │   └── util/                       # Utilities
 │   └── dist/                           # Distribution resources
-│       └── flamingock-sample.yml       # Sample configuration
+│       └── flamingock-cli.yml          # Sample configuration
 └── build.gradle.kts                    # Build configuration
 ```
 
@@ -264,4 +264,4 @@ Apache License 2.0 - See [LICENSE](../../LICENSE) file for details.
 
 - Documentation: https://docs.flamingock.io/cli
 - Issues: https://github.com/flamingock/flamingock-java/issues
-- Discussions: https://github.com/flamingock/flamingock-java/discussions
+- Discussions: https://github.com/flamingock/flamingock-java/discussions

cli/flamingock-cli/build.gradle.kts

@@ -23,6 +23,7 @@ dependencies {
     // Database clients (community edition)
     implementation("org.mongodb:mongodb-driver-sync:4.9.1")
     implementation("software.amazon.awssdk:dynamodb:2.20.0")
+    implementation ("com.couchbase.client:java-client:3.7.3")
 
     // SLF4J API - needed for interface compatibility (provided by flamingock-core)
     // implementation("org.slf4j:slf4j-api:1.7.36") // Already provided by core dependencies
@@ -36,6 +37,7 @@ dependencies {
     testImplementation("org.assertj:assertj-core:3.24.2")
     testImplementation("org.testcontainers:junit-jupiter:1.19.3")
     testImplementation("org.testcontainers:mongodb:1.19.3")
+    testImplementation("org.testcontainers:couchbase:1.21.3")
     testImplementation("com.github.stefanbirkner:system-lambda:1.2.1")
 
 }
@@ -86,7 +88,7 @@ val distImage by tasks.registering(Sync::class) {
         into("lib")
     }
     from("src/dist") {
-        into(".")
+        into("bin")
     }
 }
 
@@ -95,7 +97,9 @@ val distZip by tasks.registering(Zip::class) {
     description = "Builds the ZIP distribution"
     dependsOn(distImage)
 
-    from(distImage.get().destinationDir)
+    from(distImage.get().destinationDir) {
+        into("flamingock-cli")
+    }
 
     archiveBaseName.set("flamingock-cli")
     archiveVersion.set("")
@@ -109,7 +113,9 @@ val distTar by tasks.registering(Tar::class) {
     description = "Builds the TAR distribution"
     dependsOn(distImage)
 
-    from(distImage.get().destinationDir)
+    from(distImage.get().destinationDir) {
+        into("flamingock-cli")
+    }
 
     archiveBaseName.set("flamingock-cli")
     archiveVersion.set("")

cli/flamingock-cli/src/dist/flamingock-cli.yml

@@ -0,0 +1,28 @@
+# Flamingock CLI Configuration Sample
+# Modify this file as needed
+
+flamingock:
+  service-identifier: "flamingock-cli"
+  audit:
+
+    # MongoDB Configuration (comment to use other or modify to use)
+    mongodb:
+      connection-string: "mongodb://localhost:27017"
+      database: "test"
+      collection: "flamingockAuditLog"          # Optional, defaults to "flamingockAuditLog"
+
+    # DynamoDB Configuration (uncomment and modify to use)
+    # dynamodb:
+    #   region: "us-east-1"
+    #   table: "flamingockAuditLog"           # Optional, defaults to "flamingockAuditLog"
+    #   # endpoint: "http://localhost:8000"   # Optional for local DynamoDB
+    #   # access-key: "your-access-key"       # Optional if using IAM roles
+    #   # secret-key: "your-secret-key"       # Optional if using IAM roles
+
+    # Couchbase Configuration (uncomment and modify to use)
+    # couchbase:
+    #   endpoint: "couchbase://localhost:12110"
+    #   username: "your-username"
+    #   password: "your-password"
+    #   bucket-name: "test"
+    #   table: "flamingockAuditLog"           # Optional, defaults to "flamingockAuditLog"

cli/flamingock-cli/src/dist/flamingock-sample.yml

@@ -47,26 +47,26 @@
 )
 public class FlamingockCli implements Runnable {
 
-    @Option(names = {"-c", "--config"}, 
-            description = "Path to configuration file. Global option - must be placed before commands. (default: flamingock.yml)",
+    @Option(names = {"-c", "--config"},
+            description = "Path to configuration file. Global option - must be placed before commands. (default: flamingock-cli.yml)",
             order = 0)
-    private String configFile = "flamingock.yml";
-    
+    private String configFile = "flamingock-cli.yml";
+
     @Mixin
     private LoggingMixin loggingMixin;
 
     public static void main(String[] args) {
         FlamingockCli cli = new FlamingockCli();
         CommandLine cmd = new CommandLine(cli);
-        
+
         cmd.setExecutionStrategy(parseResult -> {
             cli.loggingMixin.initializeLogging();
             return new CommandLine.RunLast().execute(parseResult);
         });
-        
+
         // Use custom exception handler for better error messages
         cmd.setExecutionExceptionHandler(new CliExceptionHandler());
-        
+
         int exitCode = cmd.execute(args);
         System.exit(exitCode);
     }
@@ -75,12 +75,12 @@ public static void main(String[] args) {
     public void run() {
         // Initialize logging when any command is about to run
         loggingMixin.initializeLogging();
-        
+
         // This runs when no subcommand is specified - show help
         new CommandLine(this).usage(System.out);
     }
-    
+
     public String getConfigFile() {
         return configFile;
     }
-}
+}