From 8848bd8b38e0b9be5826dc300a74f19f28656725 Mon Sep 17 00:00:00 2001 From: davidfrigolet Date: Wed, 12 Aug 2026 18:48:02 +0100 Subject: [PATCH 1/2] docs: remove cli audit-list --- docs/cli/cli.md | 49 +-------------------------- docs/resources/coming-from-mongock.md | 37 +++----------------- 2 files changed, 6 insertions(+), 80 deletions(-) diff --git a/docs/cli/cli.md b/docs/cli/cli.md index 75c0290..9ffe82d 100644 --- a/docs/cli/cli.md +++ b/docs/cli/cli.md @@ -12,7 +12,7 @@ Command-line tool to execute Flamingock operations outside your application's no ## Overview -The Flamingock CLI spawns your application JAR in a separate JVM process, runs the requested operation, and returns structured results. This means you can run changes in CI/CD pipelines, audit history, diagnose issues, and fix audit states — before, after, or outside your application lifecycle. +The Flamingock CLI spawns your application JAR in a separate JVM process, runs the requested operation, and returns structured results. This means you can run changes in CI/CD pipelines, diagnose issues, and fix audit states — before, after, or outside your application lifecycle. ## Installation @@ -115,33 +115,6 @@ flamingock execute apply --jar ./my-app.jar -J -Xmx512m -J -Xms256m flamingock execute apply --jar ./my-app.jar -J -Xmx1g -- --spring.profiles.active=staging ``` -### `audit list` - -List audit entries from the change history. - -| Option | Short | Required | Description | -|--------------|-------|----------|-----------------------------------------------------------------------------| -| `--jar` | `-j` | Yes | Path to the application JAR | -| `--history` | | No | Show full chronological history instead of snapshot | -| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) | -| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) | -| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | -| `--` | | No | Separator — everything after is passed as application arguments | - -```bash -# Current state (latest per change unit) -flamingock audit list --jar ./my-app.jar - -# Full chronological history -flamingock audit list --jar ./my-app.jar --history - -# Filter entries since a specific date -flamingock audit list --jar ./my-app.jar --since 2025-01-01 - -# Show extended information (execution ID, class, method, hostname) -flamingock audit list --jar ./my-app.jar --extended -``` - ### `audit fix` Fix audit state for a change with issues. After manually verifying or fixing the state, mark the change as resolved. @@ -222,25 +195,6 @@ flamingock issue get --jar ./my-app.jar -c user-change-v2 --json ## Example output -### Audit list output - -``` -Audit Entries Snapshot (Latest per Change Unit): -================================================== - -┌──────────────────────────────┬────────┬──────────────────┬─────────────────────┐ -│ Change ID │ State │ Author │ Time │ -├──────────────────────────────┼────────┼──────────────────┼─────────────────────┤ -│ create-users-collection │ ✓ │ platform-team │ 2025-01-07 10:15:23 │ -│ add-user-indexes │ ✓ │ platform-team │ 2025-01-07 10:15:24 │ -│ seed-initial-data │ ✗ │ data-team │ 2025-01-07 10:15:25 │ -└──────────────────────────────┴────────┴──────────────────┴─────────────────────┘ - -Legend: ✓ = EXECUTED | ✗ = FAILED | ▶ = STARTED | ↩ = ROLLED_BACK - -Total entries: 3 -``` - ### Issue details output ``` @@ -338,4 +292,3 @@ If the CLI reports a missing entry point: If `issue list` shows no issues but you expect some: 1. Verify you are connecting to the correct environment 2. Check if issues were already resolved -3. Use `audit list --history` to see all historical entries diff --git a/docs/resources/coming-from-mongock.md b/docs/resources/coming-from-mongock.md index 318e8be..796106e 100644 --- a/docs/resources/coming-from-mongock.md +++ b/docs/resources/coming-from-mongock.md @@ -350,49 +350,22 @@ After the first Flamingock run against a copy of your Mongock audit history, ver Instead of inspecting the store manually, use the Flamingock CLI against your application JAR as the source of truth: ```bash -# Snapshot of the current audit state -flamingock audit list --jar ./my-app.jar - -# Optional: full audit history -flamingock audit list --jar ./my-app.jar --history - -# Optional: detect inconsistent states that require attention +# Detect inconsistent states that require attention flamingock issue list --jar ./my-app.jar ``` -Example snapshot output: - -```text -Audit Entries Snapshot (Latest per Change Unit): -================================================== - -┌──────────────────────────────┬────────┬──────────────────┬─────────────────────┐ -│ Change ID │ State │ Author │ Time │ -├──────────────────────────────┼────────┼──────────────────┼─────────────────────┤ -│ create-users-collection │ ✓ │ platform-team │ 2025-01-07 10:15:23 │ -│ add-user-indexes │ ✓ │ platform-team │ 2025-01-07 10:15:24 │ -│ seed-initial-data │ ✓ │ data-team │ 2025-01-07 10:15:25 │ -└──────────────────────────────┴────────┴──────────────────┴─────────────────────┘ - -Legend: ✓ = EXECUTED | ✗ = FAILED | ▶ = STARTED | ↩ = ROLLED_BACK - -Total: 3 entries -``` - -Successful migration signal: legacy Mongock changes appear as executed, with no failed or in-progress states left behind. +Successful migration signal: `issue list` reports no issues — no failed or in-progress states left behind from the legacy Mongock changes. Practical verification flow: 1. Run the application once with Flamingock enabled. -2. Run `flamingock audit list --jar ./my-app.jar`. -3. Confirm legacy Mongock changes that had already executed appear in the output and were not re-executed. -4. Confirm previously pending legacy changes now appear as executed. -5. Run `flamingock issue list --jar ./my-app.jar` and confirm no inconsistent audit states. +2. Run `flamingock issue list --jar ./my-app.jar` and confirm no inconsistent audit states. +3. Confirm previously pending legacy changes were applied (check application logs or the target system directly). If your application needs profiles, datasource URLs, or other runtime arguments, pass them through the CLI as well: ```bash -flamingock audit list --jar ./my-app.jar -- --spring.profiles.active=staging +flamingock issue list --jar ./my-app.jar -- --spring.profiles.active=staging ``` ## Production recommendations From 35b9b306ea18ae7e357715eba4f13a9e43bdad79 Mon Sep 17 00:00:00 2001 From: davidfrigolet Date: Mon, 17 Aug 2026 13:16:30 +0100 Subject: [PATCH 2/2] docs: mark audit list as enterprise-only feature Restores the audit list command docs removed in a prior commit, since the underlying CLI operation was kept but gated behind Cloud/Self-Hosted Edition instead of being fully removed. --- docs/cli/cli.md | 53 ++++++++++++++++++++++++++- docs/resources/coming-from-mongock.md | 35 ++++++++++++++++-- 2 files changed, 83 insertions(+), 5 deletions(-) diff --git a/docs/cli/cli.md b/docs/cli/cli.md index 9ffe82d..7a232e8 100644 --- a/docs/cli/cli.md +++ b/docs/cli/cli.md @@ -12,7 +12,7 @@ Command-line tool to execute Flamingock operations outside your application's no ## Overview -The Flamingock CLI spawns your application JAR in a separate JVM process, runs the requested operation, and returns structured results. This means you can run changes in CI/CD pipelines, diagnose issues, and fix audit states — before, after, or outside your application lifecycle. +The Flamingock CLI spawns your application JAR in a separate JVM process, runs the requested operation, and returns structured results. This means you can run changes in CI/CD pipelines, audit history, diagnose issues, and fix audit states — before, after, or outside your application lifecycle. ## Installation @@ -115,6 +115,37 @@ flamingock execute apply --jar ./my-app.jar -J -Xmx512m -J -Xms256m flamingock execute apply --jar ./my-app.jar -J -Xmx1g -- --spring.profiles.active=staging ``` +### `audit list` + +List audit entries from the change history. + +:::note +Enterprise feature. Requires Flamingock Cloud or Self-Hosted Edition. +::: + +| Option | Short | Required | Description | +|--------------|-------|----------|-------------------------------------------------------------------------------| +| `--jar` | `-j` | Yes | Path to the application JAR | +| `--history` | | No | Show full chronological history instead of snapshot | +| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) | +| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) | +| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | +| `--` | | No | Separator — everything after is passed as application arguments | + +```bash +# Current state (latest per change unit) +flamingock audit list --jar ./my-app.jar + +# Full chronological history +flamingock audit list --jar ./my-app.jar --history + +# Filter entries since a specific date +flamingock audit list --jar ./my-app.jar --since 2025-01-01 + +# Show extended information (execution ID, class, method, hostname) +flamingock audit list --jar ./my-app.jar --extended +``` + ### `audit fix` Fix audit state for a change with issues. After manually verifying or fixing the state, mark the change as resolved. @@ -195,6 +226,25 @@ flamingock issue get --jar ./my-app.jar -c user-change-v2 --json ## Example output +### Audit list output + +``` +Audit Entries Snapshot (Latest per Change Unit): +================================================== + +┌──────────────────────────────┬────────┬──────────────────┬─────────────────────┐ +│ Change ID │ State │ Author │ Time │ +├──────────────────────────────┼────────┼──────────────────┼─────────────────────┤ +│ create-users-collection │ ✓ │ platform-team │ 2025-01-07 10:15:23 │ +│ add-user-indexes │ ✓ │ platform-team │ 2025-01-07 10:15:24 │ +│ seed-initial-data │ ✗ │ data-team │ 2025-01-07 10:15:25 │ +└──────────────────────────────┴────────┴──────────────────┴─────────────────────┘ + +Legend: ✓ = EXECUTED | ✗ = FAILED | ▶ = STARTED | ↩ = ROLLED_BACK + +Total entries: 3 +``` + ### Issue details output ``` @@ -292,3 +342,4 @@ If the CLI reports a missing entry point: If `issue list` shows no issues but you expect some: 1. Verify you are connecting to the correct environment 2. Check if issues were already resolved +3. Use `audit list --history` to see all historical entries diff --git a/docs/resources/coming-from-mongock.md b/docs/resources/coming-from-mongock.md index 796106e..28d10a1 100644 --- a/docs/resources/coming-from-mongock.md +++ b/docs/resources/coming-from-mongock.md @@ -350,22 +350,49 @@ After the first Flamingock run against a copy of your Mongock audit history, ver Instead of inspecting the store manually, use the Flamingock CLI against your application JAR as the source of truth: ```bash +# Snapshot of the current audit state (Enterprise feature — Cloud or Self-Hosted Edition) +flamingock audit list --jar ./my-app.jar + +# Optional: full audit history (Enterprise feature) +flamingock audit list --jar ./my-app.jar --history + # Detect inconsistent states that require attention flamingock issue list --jar ./my-app.jar ``` -Successful migration signal: `issue list` reports no issues — no failed or in-progress states left behind from the legacy Mongock changes. +Example snapshot output: + +```text +Audit Entries Snapshot (Latest per Change Unit): +================================================== + +┌──────────────────────────────┬────────┬──────────────────┬─────────────────────┐ +│ Change ID │ State │ Author │ Time │ +├──────────────────────────────┼────────┼──────────────────┼─────────────────────┤ +│ create-users-collection │ ✓ │ platform-team │ 2025-01-07 10:15:23 │ +│ add-user-indexes │ ✓ │ platform-team │ 2025-01-07 10:15:24 │ +│ seed-initial-data │ ✓ │ data-team │ 2025-01-07 10:15:25 │ +└──────────────────────────────┴────────┴──────────────────┴─────────────────────┘ + +Legend: ✓ = EXECUTED | ✗ = FAILED | ▶ = STARTED | ↩ = ROLLED_BACK + +Total: 3 entries +``` + +Successful migration signal: legacy Mongock changes appear as executed, with no failed or in-progress states left behind. Practical verification flow: 1. Run the application once with Flamingock enabled. -2. Run `flamingock issue list --jar ./my-app.jar` and confirm no inconsistent audit states. -3. Confirm previously pending legacy changes were applied (check application logs or the target system directly). +2. Run `flamingock audit list --jar ./my-app.jar` (Enterprise) or check application logs / the target system directly. +3. Confirm legacy Mongock changes that had already executed appear as executed and were not re-executed. +4. Confirm previously pending legacy changes now appear as executed. +5. Run `flamingock issue list --jar ./my-app.jar` and confirm no inconsistent audit states. If your application needs profiles, datasource URLs, or other runtime arguments, pass them through the CLI as well: ```bash -flamingock issue list --jar ./my-app.jar -- --spring.profiles.active=staging +flamingock audit list --jar ./my-app.jar -- --spring.profiles.active=staging ``` ## Production recommendations