feat(cli): add hub bump command for dev-time version bumping

willosborne · willosborne · commit 52126bb9d9c5 · 2026-06-17T14:03:26.000+01:00
Adds calm hub bump &lt;resource&gt; &lt;file&gt; with five subcommands
(architecture, pattern, standard, control-requirement,
control-configuration). The command reads the document's $id,
checks whether that exact version already exists on the hub,
and if so bumps the version in $id on disk by the requested
change type (patch/minor/major) without pushing. If the version
is not yet published the command exits cleanly with a no-op
message.

Pairs with --fail-if-exists on hub push: developers run
hub bump before committing so CI can push the exact committed
version and fail fast if it already exists.
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
@@ -36,6 +36,12 @@ import {
     runListControls,
     runListControlConfigurations,
     ListOptions,
+    BumpOptions,
+    runBumpArchitecture,
+    runBumpPattern,
+    runBumpStandard,
+    runBumpControlRequirement,
+    runBumpControlConfiguration,
 } from './command-helpers/hub-commands';
 import type { ResourceChangeType } from '@finos/calm-shared';
 
@@ -570,6 +576,89 @@ Example:
             await runPushControlConfiguration(pushOptions);
         });
 
+    // hub bump
+    const hubBumpCmd = hubCmd.command('bump').description('Bump the version of a CALM document on disk if the current version already exists on the hub. Intended for dev-time use before committing, so CI can push with --fail-if-exists.');
+
+    hubBumpCmd
+        .command('architecture <architecture-file>')
+        .description('Bump the version of a CALM architecture on disk if that version already exists on the hub.')
+        .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
+        .addOption(hubOutputOption)
+        .addOption(hubVersionBumpOption)
+        .action(async (architectureFile, options) => {
+            const bumpOptions: BumpOptions = {
+                calmHubOptions: { calmHubUrl: options.calmHubUrl },
+                file: architectureFile,
+                format: options.format,
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+            };
+            await runBumpArchitecture(bumpOptions);
+        });
+
+    hubBumpCmd
+        .command('pattern <pattern-file>')
+        .description('Bump the version of a CALM pattern on disk if that version already exists on the hub.')
+        .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
+        .addOption(hubOutputOption)
+        .addOption(hubVersionBumpOption)
+        .action(async (patternFile, options) => {
+            const bumpOptions: BumpOptions = {
+                calmHubOptions: { calmHubUrl: options.calmHubUrl },
+                file: patternFile,
+                format: options.format,
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+            };
+            await runBumpPattern(bumpOptions);
+        });
+
+    hubBumpCmd
+        .command('standard <standard-file>')
+        .description('Bump the version of a CALM standard on disk if that version already exists on the hub.')
+        .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
+        .addOption(hubOutputOption)
+        .addOption(hubVersionBumpOption)
+        .action(async (standardFile, options) => {
+            const bumpOptions: BumpOptions = {
+                calmHubOptions: { calmHubUrl: options.calmHubUrl },
+                file: standardFile,
+                format: options.format,
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+            };
+            await runBumpStandard(bumpOptions);
+        });
+
+    hubBumpCmd
+        .command('control-requirement <requirement-file>')
+        .description('Bump the version of a control requirement on disk if that version already exists on the hub.')
+        .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
+        .addOption(hubOutputOption)
+        .addOption(hubVersionBumpOption)
+        .action(async (requirementFile, options) => {
+            const bumpOptions: BumpOptions = {
+                calmHubOptions: { calmHubUrl: options.calmHubUrl },
+                file: requirementFile,
+                format: options.format,
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+            };
+            await runBumpControlRequirement(bumpOptions);
+        });
+
+    hubBumpCmd
+        .command('control-configuration <config-file>')
+        .description('Bump the version of a control configuration on disk if that version already exists on the hub.')
+        .option(CALMHUB_URL_OPTION, 'URL to CALMHub instance')
+        .addOption(hubOutputOption)
+        .addOption(hubVersionBumpOption)
+        .action(async (configFile, options) => {
+            const bumpOptions: BumpOptions = {
+                calmHubOptions: { calmHubUrl: options.calmHubUrl },
+                file: configFile,
+                format: options.format,
+                changeType: options.changeType.toUpperCase() as ResourceChangeType,
+            };
+            await runBumpControlConfiguration(bumpOptions);
+        });
+
     // hub pull
     const hubPullCmd = hubCmd.command('pull').description('Pull a CALM document from CALM Hub');
 
diff --git a/cli/src/command-helpers/hub-commands.spec.ts b/cli/src/command-helpers/hub-commands.spec.ts
@@ -8,7 +8,8 @@ import { runCreateNamespace, runListArchitectures, runListNamespaces,
     runCreateDomain, runListDomains, runListControls,
     runPushControlRequirement, runPullControlRequirement, runPushControlConfiguration, runPullControlConfiguration,
     printIdCreateResult,
-    runListControlConfigurations } from './hub-commands';
+    runListControlConfigurations,
+    runBumpArchitecture, runBumpPattern, runBumpStandard, runBumpControlRequirement, runBumpControlConfiguration } from './hub-commands';
 
 // We stub the @finos/calm-shared HTTP client so no real HTTP is made, but keep the
 // real (pure) document-id-utils helpers that orchestratePush relies on.
@@ -1416,5 +1417,218 @@ describe('hub-commands', () => {
         });
     });
 
+    // ── runBumpArchitecture ────────────────────────────────────────────────────
+
+    describe('runBumpArchitecture', () => {
+        it('bumps the version on disk when the current version already exists on the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'PATCH' });
+
+            expect(mockClient.getMappedResourceVersions).toHaveBeenCalledWith('finos', 'my-arch', 'architectures');
+            expect(fs.writeFile).toHaveBeenCalledWith('arch.json', expect.stringContaining('/versions/1.0.1'), 'utf-8');
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(
+                expect.objectContaining({ file: 'arch.json', previousVersion: '1.0.0', newVersion: '1.0.1' })
+            );
+        });
+
+        it('bumps by minor when changeType is MINOR', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'MINOR' });
+
+            expect(fs.writeFile).toHaveBeenCalledWith('arch.json', expect.stringContaining('/versions/1.1.0'), 'utf-8');
+        });
+
+        it('bumps by major when changeType is MAJOR', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'MAJOR' });
+
+            expect(fs.writeFile).toHaveBeenCalledWith('arch.json', expect.stringContaining('/versions/2.0.0'), 'utf-8');
+        });
+
+        it('does not write the file and prints a no-op message when the version is not yet published', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue([]);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'PATCH' });
+
+            expect(fs.writeFile).not.toHaveBeenCalled();
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(
+                expect.objectContaining({ bumped: false })
+            );
+        });
+
+        it('does not write the file when the exact on-disk version is not in the hub versions list', async () => {
+            const { mockClient } = await getSharedMocks();
+            // Hub has 2.0.0 but file has 1.0.0 — version mismatch, no bump
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['2.0.0']);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'PATCH' });
+
+            expect(fs.writeFile).not.toHaveBeenCalled();
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(expect.objectContaining({ bumped: false }));
+        });
+
+        it('does not push to the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'PATCH' });
+
+            expect(mockClient.createMappedResourceVersion).not.toHaveBeenCalled();
+        });
+
+        it('renders a pretty table when format is pretty', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'PATCH', format: 'pretty' });
+
+            expect(hubOutput.printTableSuccess).toHaveBeenCalledWith(
+                [{ FILE: 'arch.json', FROM: '1.0.0', TO: '1.0.1' }],
+                expect.arrayContaining([expect.objectContaining({ key: 'FROM' }), expect.objectContaining({ key: 'TO' })])
+            );
+        });
+
+        it('exits on HubClientError', async () => {
+            const { mockClient, shared } = await getSharedMocks();
+            vi.mocked(mockClient.getMappedResourceVersions).mockRejectedValue(
+                new shared.HubClientError(503, 'Service unavailable', 'GET /calm/namespaces/finos/architectures/my-arch/versions')
+            );
+
+            await expect(runBumpArchitecture({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'arch.json', changeType: 'PATCH' }))
+                .rejects.toThrow('process.exit');
+            expect(hubOutput.printError).toHaveBeenCalledWith(503, 'Service unavailable', expect.any(String), 'json');
+        });
+    });
+
+    describe('runBumpPattern', () => {
+        it('bumps the version on disk when the current version already exists on the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(pushDoc('my-pattern', 'patterns') as unknown as Uint8Array);
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpPattern({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'pattern.json', changeType: 'PATCH' });
+
+            expect(mockClient.getMappedResourceVersions).toHaveBeenCalledWith('finos', 'my-pattern', 'patterns');
+            expect(fs.writeFile).toHaveBeenCalledWith('pattern.json', expect.stringContaining('/versions/1.0.1'), 'utf-8');
+        });
+    });
+
+    describe('runBumpStandard', () => {
+        it('bumps the version on disk when the current version already exists on the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(pushDoc('my-standard', 'standards') as unknown as Uint8Array);
+            vi.mocked(mockClient.getMappedResourceVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpStandard({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'standard.json', changeType: 'PATCH' });
+
+            expect(mockClient.getMappedResourceVersions).toHaveBeenCalledWith('finos', 'my-standard', 'standards');
+            expect(fs.writeFile).toHaveBeenCalledWith('standard.json', expect.stringContaining('/versions/1.0.1'), 'utf-8');
+        });
+    });
+
+    // ── runBumpControlRequirement ──────────────────────────────────────────────
+
+    describe('runBumpControlRequirement', () => {
+        it('bumps the version on disk when the current version already exists on the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(controlReqDoc() as unknown as Uint8Array);
+            vi.mocked(mockClient.getControlRequirementVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpControlRequirement({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'req.json', changeType: 'PATCH' });
+
+            expect(mockClient.getControlRequirementVersions).toHaveBeenCalledWith('security', 'access-control');
+            expect(fs.writeFile).toHaveBeenCalledWith('req.json', expect.stringContaining('/requirement/versions/1.0.1'), 'utf-8');
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(
+                expect.objectContaining({ file: 'req.json', previousVersion: '1.0.0', newVersion: '1.0.1' })
+            );
+        });
+
+        it('does not write the file when the current version is not yet published', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(controlReqDoc() as unknown as Uint8Array);
+            vi.mocked(mockClient.getControlRequirementVersions).mockResolvedValue([]);
+
+            await runBumpControlRequirement({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'req.json', changeType: 'PATCH' });
+
+            expect(fs.writeFile).not.toHaveBeenCalled();
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(expect.objectContaining({ bumped: false }));
+        });
+
+        it('does not push to the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(controlReqDoc() as unknown as Uint8Array);
+            vi.mocked(mockClient.getControlRequirementVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpControlRequirement({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'req.json', changeType: 'PATCH' });
+
+            expect(mockClient.createControlRequirementVersion).not.toHaveBeenCalled();
+        });
+
+        it('exits when the document $id describes a configuration, not a requirement', async () => {
+            vi.mocked(fs.readFile).mockResolvedValue(controlConfigDoc() as unknown as Uint8Array);
+
+            await expect(runBumpControlRequirement({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'req.json', changeType: 'PATCH' }))
+                .rejects.toThrow('process.exit');
+            expect(hubOutput.printError).toHaveBeenCalledWith(
+                0, expect.stringContaining('describes a control configuration, but a control requirement was expected'), expect.any(String), 'json'
+            );
+        });
+    });
+
+    // ── runBumpControlConfiguration ────────────────────────────────────────────
+
+    describe('runBumpControlConfiguration', () => {
+        it('bumps the version on disk when the current version already exists on the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(controlConfigDoc() as unknown as Uint8Array);
+            vi.mocked(mockClient.getControlConfigurationVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpControlConfiguration({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'config.json', changeType: 'PATCH' });
+
+            expect(mockClient.getControlConfigurationVersions).toHaveBeenCalledWith('security', 'access-control', 'prod');
+            expect(fs.writeFile).toHaveBeenCalledWith('config.json', expect.stringContaining('/configurations/prod/versions/1.0.1'), 'utf-8');
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(
+                expect.objectContaining({ file: 'config.json', previousVersion: '1.0.0', newVersion: '1.0.1' })
+            );
+        });
+
+        it('does not write the file when the current version is not yet published', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(controlConfigDoc() as unknown as Uint8Array);
+            vi.mocked(mockClient.getControlConfigurationVersions).mockResolvedValue([]);
+
+            await runBumpControlConfiguration({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'config.json', changeType: 'PATCH' });
+
+            expect(fs.writeFile).not.toHaveBeenCalled();
+            expect(hubOutput.printJsonSuccess).toHaveBeenCalledWith(expect.objectContaining({ bumped: false }));
+        });
+
+        it('does not push to the hub', async () => {
+            const { mockClient } = await getSharedMocks();
+            vi.mocked(fs.readFile).mockResolvedValue(controlConfigDoc() as unknown as Uint8Array);
+            vi.mocked(mockClient.getControlConfigurationVersions).mockResolvedValue(['1.0.0']);
+
+            await runBumpControlConfiguration({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'config.json', changeType: 'PATCH' });
+
+            expect(mockClient.createControlConfigurationVersion).not.toHaveBeenCalled();
+        });
+
+        it('exits when the document $id describes a requirement, not a configuration', async () => {
+            vi.mocked(fs.readFile).mockResolvedValue(controlReqDoc() as unknown as Uint8Array);
+
+            await expect(runBumpControlConfiguration({ calmHubOptions: { calmHubUrl: 'http://hub' }, file: 'config.json', changeType: 'PATCH' }))
+                .rejects.toThrow('process.exit');
+            expect(hubOutput.printError).toHaveBeenCalledWith(
+                0, expect.stringContaining('describes a control requirement, but a control configuration was expected'), expect.any(String), 'json'
+            );
+        });
+    });
 
 });
diff --git a/cli/src/command-helpers/hub-commands.ts b/cli/src/command-helpers/hub-commands.ts
