feat(cli): add --fail-if-modified to hub push (finos#2760)

* feat(cli): add --fail-if-modified to hub push

Introduces a shared, key-order-insensitive content comparison
(`canonicalEqual` in @finos/calm-shared) and uses it to add a strict,
non-bumping `--fail-if-modified` mode to `calm hub push` for
architecture, pattern and standard documents:

- brand-new mapping  -> created at 1.0.0 (unchanged behaviour)
- exists + unchanged -> skipped (no new version, file left as-is)
- exists + modified  -> push fails

Default behaviour (auto-bump) is unchanged. The comparison helper is
shared so it can be reused by other push paths without duplication.

Claude-Session: https://claude.ai/code/session_01QiHAHdi4d4mCoy4wku5s2v

* fix(cli): correct hub push --fail-if-modified comparison and extend to control docs

Addresses review feedback on the strict-push comparison:

- Normalise the local document the same way Hub stores it (rewriting the
  $id to the latest version and applying default fields via
  updateDocumentMetadata) before comparing, so a version-only difference
  (e.g. another committer auto-bumped Hub) or an absent `description` no
  longer reports a false "has changed".
- Guard against an empty/unreadable latest-version body: surface a clear
  "could not read" error instead of silently reporting "has changed".
- Point users at --change-type in the modified-document error message.
- Extend --fail-if-modified to `control-requirement` and
  `control-configuration` push (same normalise-and-compare model).
- Add Commander argv wiring tests so the flag plumbing is covered.

Claude-Session: https://claude.ai/code/session_01QiHAHdi4d4mCoy4wku5s2v

Author: willosborne

cli/AGENTS.md

@@ -59,6 +59,7 @@ npm run copy-ai-tools         # Copy AI agent files from ../calm-ai/
 9. **hub** - Command **group** for interacting with CALM Hub. Subcommands:
    - `hub push <resource> <file>` / `hub pull <resource>` / `hub list <resources>` / `hub create <resource>`
    - Resources span architectures, patterns, standards, control-requirements, control-configurations, namespaces, and domains (which subcommands exist varies per verb).
+   - `hub push` auto-bumps by default (creates a new version off the latest). The `--fail-if-modified` flag (supported on `architecture`, `pattern`, `standard`, `control-requirement` and `control-configuration`) switches to a strict, non-bumping mode: a brand-new mapping is still created at `1.0.0`, an unchanged document is skipped, and a document that differs from the latest published version fails the push. The local document is normalised the same way Hub stores it (via `updateDocumentMetadata`/`updateControlDocumentMetadata`) before comparing with `canonicalEqual` from `@finos/calm-shared`, so a version-only or defaulted-field difference is not mistaken for a content change.
 
 ### Important Directories
 ```

cli/src/cli.spec.ts

@@ -784,6 +784,31 @@ describe('CLI Commands', () => {
             }));
         });
 
+        it('passes --fail-if-modified through to the architecture handler', async () => {
+            await program.parseAsync([
+                'node', 'cli.js', 'hub', 'push', 'architecture',
+                'arch.json',
+                '--calm-hub-url', 'http://hub',
+                '--fail-if-modified',
+            ]);
+
+            expect(hubCommandsModule.runPushArchitecture).toHaveBeenCalledWith(expect.objectContaining({
+                failIfModified: true,
+            }));
+        });
+
+        it('defaults --fail-if-modified to false when not provided', async () => {
+            await program.parseAsync([
+                'node', 'cli.js', 'hub', 'push', 'architecture',
+                'arch.json',
+                '--calm-hub-url', 'http://hub',
+            ]);
+
+            expect(hubCommandsModule.runPushArchitecture).toHaveBeenCalledWith(expect.objectContaining({
+                failIfModified: false,
+            }));
+        });
+
         it('passes --format pretty through to the handler', async () => {
             await program.parseAsync([
                 'node', 'cli.js', 'hub', 'push', 'architecture',
@@ -1087,6 +1112,18 @@ describe('CLI Commands', () => {
                 changeType: 'PATCH',
             }));
         });
+
+        it('passes --fail-if-modified through to the handler', async () => {
+            await program.parseAsync([
+                'node', 'cli.js', 'hub', 'push', 'control-requirement', 'req.json',
+                '--calm-hub-url', 'http://hub',
+                '--fail-if-modified',
+            ]);
+
+            expect(hubCommandsModule.runPushControlRequirement).toHaveBeenCalledWith(expect.objectContaining({
+                failIfModified: true,
+            }));
+        });
     });
 
     describe('pull control-requirement command', () => {

cli/src/cli.ts

@@ -463,6 +463,9 @@ Example:
         .choices(['patch', 'minor', 'major'])
         .default('patch');
 
+    const hubFailIfModifiedOption = new Option('--fail-if-modified', 'Strict mode: do not auto-bump. Skip if the document is unchanged from the latest published version; fail if it has changed. A brand-new mapping is still created at 1.0.0.')
+        .default(false);
+
     const hubCmd = new Command('hub').description('Interact with CALM Hub');
 
     // hub push
@@ -476,14 +479,16 @@ Example:
         .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
         .addOption(hubOutputOption)
         .addOption(hubVersionBumpOption)
+        .addOption(hubFailIfModifiedOption)
         .action(async (architectureFile, options) => {
             const pushOptions: PushOptions = {
                 calmHubOptions: { calmHubUrl: options.calmHubUrl },
                 name: options.name,
                 description: options.description,
                 file: architectureFile,
                 format: options.format,
-                changeType: options.changeType.toUpperCase() as ResourceChangeType
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+                failIfModified: options.failIfModified
             };
             await runPushArchitecture(pushOptions);
         });
@@ -496,6 +501,7 @@ Example:
         .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
         .addOption(hubOutputOption)
         .addOption(hubVersionBumpOption)
+        .addOption(hubFailIfModifiedOption)
         .action(async (patternFile, options) => {
             const pushPatternOptions: PushOptions = {
                 calmHubOptions: { calmHubUrl: options.calmHubUrl },
@@ -504,6 +510,7 @@ Example:
                 file: patternFile,
                 format: options.format,
                 changeType: options.changeType.toUpperCase() as ResourceChangeType,
+                failIfModified: options.failIfModified
             };
             await runPushPattern(pushPatternOptions);
         });
@@ -516,6 +523,7 @@ Example:
         .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
         .addOption(hubOutputOption)
         .addOption(hubVersionBumpOption)
+        .addOption(hubFailIfModifiedOption)
         .action(async (standardFile, options) => {
             const pushStandardOptions: PushOptions = {
                 calmHubOptions: { calmHubUrl: options.calmHubUrl },
@@ -524,6 +532,7 @@ Example:
                 file: standardFile,
                 format: options.format,
                 changeType: options.changeType.toUpperCase() as ResourceChangeType,
+                failIfModified: options.failIfModified
             };
             await runPushStandard(pushStandardOptions);
         });
@@ -534,12 +543,14 @@ Example:
         .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
         .addOption(hubOutputOption)
         .addOption(hubVersionBumpOption)
+        .addOption(hubFailIfModifiedOption)
         .action(async (requirementFile, options) => {
             const pushOptions: PushControlOptions = {
                 calmHubOptions: { calmHubUrl: options.calmHubUrl },
                 file: requirementFile,
                 format: options.format,
-                changeType: options.changeType.toUpperCase() as ResourceChangeType
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+                failIfModified: options.failIfModified
             };
             await runPushControlRequirement(pushOptions);
         });
@@ -550,12 +561,14 @@ Example:
         .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
         .addOption(hubOutputOption)
         .addOption(hubVersionBumpOption)
+        .addOption(hubFailIfModifiedOption)
         .action(async (configFile, options) => {
             const pushOptions: PushControlOptions = {
                 calmHubOptions: { calmHubUrl: options.calmHubUrl },
                 file: configFile,
                 format: options.format,
-                changeType: options.changeType.toUpperCase() as ResourceChangeType
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+                failIfModified: options.failIfModified
             };
             await runPushControlConfiguration(pushOptions);
         });