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

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 architecture|pattern|standard` auto-bumps by default (creates a new version off the latest). The `--fail-if-modified` flag 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. Content comparison uses `canonicalEqual` from `@finos/calm-shared` (key-order-insensitive).
 
 ### Important Directories
 ```

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);
         });

cli/src/command-helpers/hub-commands.spec.ts

@@ -16,6 +16,8 @@ vi.mock('@finos/calm-shared', async () => {
     const documentIdUtils = await vi.importActual<Record<string, unknown>>('@finos/calm-shared/dist/hub/document-id-utils');
     // Real (pure) semver helpers used by pushDocument's version-bump path.
     const semver = await vi.importActual('@finos/calm-shared/dist/hub/semver');
+    // Real (pure) canonical-equality helper used by pushDocument's fail-if-modified path.
+    const canonical = await vi.importActual('@finos/calm-shared/dist/hub/canonical');
     const mockClient = {
         createNamespace: vi.fn(),
         listNamespaces: vi.fn(),
@@ -41,6 +43,7 @@ vi.mock('@finos/calm-shared', async () => {
         ...documentIdUtils,
         extractDocumentMetadata: vi.fn(documentIdUtils['extractDocumentMetadata'] as (...args: unknown[]) => unknown),
         ...semver,
+        ...canonical,
         CalmHubClient: vi.fn(function () { return mockClient; }),
         HubClientError: class HubClientError extends Error {
             constructor(public status: number, public error: string, public request: string) {
@@ -311,6 +314,74 @@ describe('hub-commands', () => {
                 0, expect.stringContaining('namespace and mapping'), expect.any(String), 'json'
             );
         });
+
+        describe('--fail-if-modified', () => {
+            it('creates 1.0.0 for a brand-new mapping even with the flag set', async () => {
+                const { mockClient } = await getSharedMocks();
+                vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue([]);
+                vi.mocked(mockClient.createMappedResourceVersion).mockResolvedValue(
+                    'http://hub/calm/namespaces/finos/architectures/my-arch/versions/1.0.0'
+                );
+
+                await runPushArchitecture({
+                    calmHubOptions: { calmHubUrl: 'http://hub' },
+                    file: 'arch.json',
+                    failIfModified: true
+                });
+
+                expect(mockClient.getMappedResourceByVersion).not.toHaveBeenCalled();
+                expect(mockClient.createMappedResourceVersion).toHaveBeenCalledWith(
+                    expect.objectContaining({ version: '1.0.0' }),
+                    expect.any(String)
+                );
+                expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(
+                    expect.objectContaining({ status: 'created', version: '1.0.0' })
+                );
+            });
+
+            it('skips (does not create a new version) when content is unchanged from the latest published version', async () => {
+                const { mockClient } = await getSharedMocks();
+                vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+                // Latest published version is byte-identical to the local document (key order ignored).
+                vi.mocked(mockClient.getMappedResourceByVersion).mockResolvedValue(JSON.parse(pushDoc('my-arch')));
+
+                await runPushArchitecture({
+                    calmHubOptions: { calmHubUrl: 'http://hub' },
+                    file: 'arch.json',
+                    failIfModified: true
+                });
+
+                expect(mockClient.getMappedResourceByVersion).toHaveBeenCalledWith('finos', 'my-arch', '1.0.0', 'architectures');
+                expect(mockClient.createMappedResourceVersion).not.toHaveBeenCalled();
+                expect(fs.writeFile).not.toHaveBeenCalled();
+                expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(
+                    expect.objectContaining({ status: 'skipped', version: '1.0.0' })
+                );
+            });
+
+            it('fails when the document has changed relative to the latest published version', async () => {
+                const { mockClient } = await getSharedMocks();
+                vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+                // Latest published version differs from the local document.
+                vi.mocked(mockClient.getMappedResourceByVersion).mockResolvedValue({
+                    $id: 'http://hub/calm/namespaces/finos/architectures/my-arch/versions/1.0.0',
+                    title: 'my-arch',
+                    nodes: [{ 'unique-id': 'added-on-disk' }]
+                });
+
+                await expect(runPushArchitecture({
+                    calmHubOptions: { calmHubUrl: 'http://hub' },
+                    file: 'arch.json',
+                    failIfModified: true
+                })).rejects.toThrow('process.exit');
+
+                expect(mockClient.createMappedResourceVersion).not.toHaveBeenCalled();
+                expect(fs.writeFile).not.toHaveBeenCalled();
+                expect(hubOutput.printError).toHaveBeenCalledWith(
+                    0, expect.stringContaining('has changed relative to the latest published version'), expect.any(String), 'json'
+                );
+            });
+        });
     });
 
     // ── runPullArchitecture ────────────────────────────────────────────────
@@ -517,7 +588,7 @@ describe('hub-commands', () => {
     describe('printPushResult', () => {
         it('calls printTableSuccess with correct columns when format is pretty', async () => {
             printPushResult(
-                { mapping: 'my-arch', version: '1.0.0', namespace: 'finos', location: 'http://hub' },
+                { status: 'created', mapping: 'my-arch', version: '1.0.0', namespace: 'finos', location: 'http://hub' },
                 'pretty'
             );
 
@@ -533,8 +604,20 @@ describe('hub-commands', () => {
             expect(hubOutput.printJsonSuccess).not.toHaveBeenCalled();
         });
 
+        it('shows an Unchanged status for a skipped push', async () => {
+            printPushResult(
+                { status: 'skipped', mapping: 'my-arch', version: '1.0.0', namespace: 'finos', location: 'http://hub' },
+                'pretty'
+            );
+
+            expect(hubOutput.printTableSuccess).toHaveBeenCalledWith(
+                [{ STATUS: 'Unchanged', MAPPING: 'my-arch', VERSION: '1.0.0', LOCATION: 'http://hub' }],
+                expect.anything()
+            );
+        });
+
         it('calls printJsonSuccess when format is json', async () => {
-            const result = { mapping: 'my-arch', version: '1.0.0', namespace: 'finos', location: '/loc' };
+            const result = { status: 'created' as const, mapping: 'my-arch', version: '1.0.0', namespace: 'finos', location: '/loc' };
             printPushResult(result, 'json');
 
             expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(result);

cli/src/command-helpers/hub-commands.ts

@@ -1,5 +1,5 @@
 import { readFile, writeFile } from 'fs/promises';
-import { CalmHubClient, CalmHubOptions, HubClientError, HubDomainSummary, HubControlSummary, HubDomainCreateResult, DocumentMetadata, extractDocumentMetadata, computeSemVerBump, sortSemVer, ResourceChangeType, ResourceType, updateDocumentMetadata, constructDocumentId, ControlDocumentMetadata, ControlDocumentKind, extractControlMetadata, updateControlDocumentMetadata } from '@finos/calm-shared';
+import { CalmHubClient, CalmHubOptions, HubClientError, HubDomainSummary, HubControlSummary, HubDomainCreateResult, DocumentMetadata, extractDocumentMetadata, computeSemVerBump, sortSemVer, ResourceChangeType, ResourceType, updateDocumentMetadata, constructDocumentId, ControlDocumentMetadata, ControlDocumentKind, extractControlMetadata, updateControlDocumentMetadata, canonicalEqual } from '@finos/calm-shared';
 import { OutputFormat, parseOutputFormat, printError, printJsonSuccess, printTableSuccess } from './hub-output';
 import * as cliConfig from '../cli-config';
 
@@ -58,24 +58,41 @@ export interface PushOptions {
     version?: string;
     format?: string;
     changeType?: ResourceChangeType;
+    /**
+     * Strict mode. When set, push does not auto-bump: if the mapping already exists, the local
+     * document is compared to the latest published version. Unchanged content is skipped; changed
+     * content fails the push (so a merge introduces only the versions it claims). A brand-new
+     * mapping is still created at 1.0.0.
+     */
+    failIfModified?: boolean;
 }
 
+/** Whether a push created a new version or skipped because the content was unchanged. */
+export type PushAction = 'created' | 'skipped';
+
 export interface PushResult {
+    status: PushAction;
     version: string;
     mapping: string;
     namespace: string;
     location: string;
 }
 
+export interface PushDocumentResult {
+    action: PushAction;
+    metadata: DocumentMetadata;
+}
+
 /**
  * Prints a push operation result in either pretty table or JSON format.
  * @param result Push result payload.
  * @param format Output format selector.
  */
 export function printPushResult(result: PushResult, format: OutputFormat): void {
     if (format === 'pretty') {
+        const statusLabel = result.status === 'created' ? 'Created' : 'Unchanged';
         printTableSuccess(
-            [{ STATUS: 'Created', MAPPING: result.mapping, VERSION: result.version, LOCATION: result.location }],
+            [{ STATUS: statusLabel, MAPPING: result.mapping, VERSION: result.version, LOCATION: result.location }],
             [
                 { key: 'STATUS', header: 'STATUS' },
                 { key: 'MAPPING', header: 'MAPPING' },
@@ -177,7 +194,7 @@ export async function pushDocument(
     fileContent: string, 
     resourceType: ResourceType,
     changeType: ResourceChangeType,
-    options: PushOptions): Promise<DocumentMetadata> {
+    options: PushOptions): Promise<PushDocumentResult> {
 
     // allow changing of name/description if not already set.
     const name = options.name ?? metadata.name;
@@ -197,6 +214,23 @@ export async function pushDocument(
         // Sort defensively so the highest version is last, regardless of the order Hub returns them in.
         const sortedVersions = sortSemVer(mappedResourceVersions);
         const latestVersion = sortedVersions[sortedVersions.length - 1];
+
+        if (options.failIfModified) {
+            // Strict mode: don't auto-bump. Compare the local document to the latest published
+            // version — skip when unchanged, fail when it differs.
+            const latest = await client.getMappedResourceByVersion(namespace, mapping, latestVersion, resourceType);
+            if (canonicalEqual(JSON.parse(fileContent), latest)) {
+                newDocumentMetadata.version = latestVersion;
+                return { action: 'skipped', metadata: newDocumentMetadata };
+            }
+            throw new HubCommandError(
+                0,
+                `Document '${mapping}' has changed relative to the latest published version (${latestVersion}) in CALM Hub. ` +
+                'Re-run without --fail-if-modified to publish a new version.',
+                `push ${resourceType} ${options.file}`
+            );
+        }
+
         const newVersion = computeSemVerBump(latestVersion, changeType);
         newDocumentMetadata.version = newVersion;
         fileContent = updateDocumentMetadata(fileContent, newDocumentMetadata);
@@ -206,7 +240,7 @@ export async function pushDocument(
         fileContent = updateDocumentMetadata(fileContent, newDocumentMetadata);
         await client.createMappedResourceVersion(newDocumentMetadata, fileContent);
     }
-    return newDocumentMetadata;
+    return { action: 'created', metadata: newDocumentMetadata };
 }
 
 /**
@@ -237,20 +271,24 @@ export async function orchestratePush(options: PushOptions, resourceType: Resour
     const namespace = metadata.namespace;
     const mapping = metadata.mapping;
 
-    let documentMetadata: DocumentMetadata;
     try {
-        documentMetadata = await pushDocument(
-            client, 
-            namespace, 
-            mapping, 
-            metadata, 
-            fileContent, 
-            resourceType, 
-            options.changeType ?? 'PATCH', 
+        const { action, metadata: documentMetadata } = await pushDocument(
+            client,
+            namespace,
+            mapping,
+            metadata,
+            fileContent,
+            resourceType,
+            options.changeType ?? 'PATCH',
             options);
-        const newDocument = updateDocumentMetadata(fileContent, documentMetadata);
-        await writeFile(options.file, newDocument, 'utf-8');
+        // Only rewrite the on-disk document when a new version was actually created; an unchanged
+        // document is left exactly as it is.
+        if (action === 'created') {
+            const newDocument = updateDocumentMetadata(fileContent, documentMetadata);
+            await writeFile(options.file, newDocument, 'utf-8');
+        }
         const result: PushResult = {
+            status: action,
             mapping,
             version: documentMetadata.version!,
             namespace,

shared/src/hub/canonical.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { canonicalEqual, canonicalize } from './canonical';
+
+describe('canonical', () => {
+    describe('canonicalEqual', () => {
+        it('treats key-reordered objects as equal', () => {
+            expect(canonicalEqual({ a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true);
+        });
+
+        it('treats nested key-reordered objects as equal', () => {
+            expect(canonicalEqual(
+                { outer: { a: 1, b: { c: 3, d: 4 } } },
+                { outer: { b: { d: 4, c: 3 }, a: 1 } }
+            )).toBe(true);
+        });
+
+        it('detects value differences', () => {
+            expect(canonicalEqual({ a: 1 }, { a: 2 })).toBe(false);
+        });
+
+        it('is sensitive to array order', () => {
+            expect(canonicalEqual({ a: [1, 2] }, { a: [2, 1] })).toBe(false);
+        });
+
+        it('compares primitives directly', () => {
+            expect(canonicalEqual('x', 'x')).toBe(true);
+            expect(canonicalEqual('x', 'y')).toBe(false);
+        });
+    });
+
+    describe('canonicalize', () => {
+        it('sorts object keys recursively while preserving array order', () => {
+            expect(JSON.stringify(canonicalize({ b: 2, a: [{ y: 1, x: 2 }] })))
+                .toBe(JSON.stringify({ a: [{ x: 2, y: 1 }], b: 2 }));
+        });
+    });
+});

shared/src/hub/canonical.ts

@@ -0,0 +1,23 @@
+/**
+ * Recursively sort object keys so two documents with the same content but different key ordering
+ * compare equal. Array order is preserved.
+ */
+export function canonicalize(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        const sorted: Record<string, unknown> = {};
+        for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+            sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+
+/**
+ * Deep content equality that ignores object key ordering (array order is preserved). Used to decide
+ * whether a local CALM document differs from the version CalmHub has already published.
+ */
+export function canonicalEqual(a: unknown, b: unknown): boolean {
+    return JSON.stringify(canonicalize(a)) === JSON.stringify(canonicalize(b));
+}

shared/src/index.ts

@@ -87,6 +87,7 @@ export {
     type ControlDocumentKind
 } from './hub/document-id-utils.js';
 export { computeSemVerBump, compareSemVer, sortSemVer } from './hub/semver.js';
+export { canonicalEqual, canonicalize } from './hub/canonical.js';
 export {
     enrichWithDocumentPositions,
     parseDocumentWithPositions,