SP-355: Implement diff with file (#362)

tneum-celonis · web-flow · commit e08c05ae076d · 2026-05-29T16:36:29.000+02:00
diff --git a/docs/user-guide/config-commands.md b/docs/user-guide/config-commands.md
@@ -717,7 +717,9 @@ content-cli config nodes list --packageKey my-package --packageVersion 1.2.3 --l
 
 ## Diffing Node Configurations
 
-The **config nodes diff** command allows you to compare two versions of a node's configuration within a package.
+The **config nodes diff** command allows you to compare two versions of a node's configuration within a package, or to compare a local node JSON file against a remote version.
+
+Exactly one of `--compareVersion` or `--file` must be provided; the two options are mutually exclusive.
 
 ### Diff Two Versions of a Node
 
@@ -764,6 +766,18 @@ The `changes` field contains configuration changes in JSON Patch format with the
 
 The `metadataChanges` field follows the same structure but represents changes to node metadata rather than configuration.
 
+### Diff a Local Node File Against a Database Version
+
+To diff a local node JSON file (the compare side) against a version of the node stored remotely (the base side), use the `--file` option instead of `--compareVersion`:
+
+```bash
+content-cli config nodes diff --packageKey <packageKey> --nodeKey <nodeKey> --baseVersion <STAGING|version> --file <node.json>
+```
+
+The file must follow the `NodeExportTransport` shape — the format produced by `config export --unzip` under `<packageKey>_<version>/nodes/<nodeKey>.json`. `--baseVersion` accepts either `STAGING` or a specific package version. `--file` and `--compareVersion` are mutually exclusive; exactly one must be provided.
+
+If no node with the given key exists for the resolved base version, the file is diffed against an empty configuration `{}`.
+
 ### Export Node Diff as JSON
 
 To export the node diff as a JSON file, use the `--json` option:
diff --git a/src/commands/configuration-management/api/node-diff-api.ts b/src/commands/configuration-management/api/node-diff-api.ts
@@ -1,6 +1,11 @@
+import * as FormData from "form-data";
 import { HttpClient } from "../../../core/http/http-client";
 import { Context } from "../../../core/command/cli-context";
-import { GetNodeDiffRequest, NodeConfigurationDiffTransport } from "../interfaces/node-diff.interfaces";
+import {
+    GetNodeDiffRequest,
+    GetNodeDiffWithFileRequest,
+    NodeConfigurationDiffTransport,
+} from "../interfaces/node-diff.interfaces";
 import { FatalError } from "../../../core/utils/logger";
 
 export class NodeDiffApi {
@@ -22,4 +27,21 @@ export class NodeDiffApi {
                 throw new FatalError(`Problem getting the node diff: ${exception}`);
             });
     }
+
+    public async diffWithFile(request: GetNodeDiffWithFileRequest): Promise<NodeConfigurationDiffTransport> {
+        const queryParams = new URLSearchParams();
+        queryParams.set("baseVersion", request.baseVersion);
+
+        const formData = new FormData();
+        formData.append("file", request.file);
+
+        return this.httpClient()
+            .postFile(
+                `/pacman/api/core/packages/${request.packageKey}/nodes/${request.nodeKey}/diff/configuration/with-file?${queryParams.toString()}`,
+                formData,
+            )
+            .catch(exception => {
+                throw new FatalError(`Problem getting the node diff: ${exception}`);
+            });
+    }
 }
diff --git a/src/commands/configuration-management/interfaces/node-diff.interfaces.ts b/src/commands/configuration-management/interfaces/node-diff.interfaces.ts
@@ -1,3 +1,4 @@
+import { ReadStream } from "node:fs";
 import { ConfigurationChangeTransport, NodeConfigurationChangeType } from "./diff-package.interfaces";
 
 export interface GetNodeDiffRequest {
@@ -7,6 +8,13 @@ export interface GetNodeDiffRequest {
     compareVersion: string;
 }
 
+export interface GetNodeDiffWithFileRequest {
+    packageKey: string;
+    nodeKey: string;
+    baseVersion: string;
+    file: ReadStream;
+}
+
 export interface NodeConfigurationDiffTransport {
     packageKey: string,
     nodeKey: string,
diff --git a/src/commands/configuration-management/module.ts b/src/commands/configuration-management/module.ts
@@ -163,7 +163,8 @@ class Module extends IModule {
             .requiredOption("--packageKey <packageKey>", "Identifier of the package")
             .requiredOption("--nodeKey <nodeKey>", "Identifier of the node")
             .requiredOption("--baseVersion <baseVersion>", "Base version of the node")
-            .requiredOption("--compareVersion <compareVersion>", "Compare version of the node")
+            .option("--compareVersion <compareVersion>", "Compare version of the node, mutually exclusive with --file (exactly one required)")
+            .option("-f, --file <file>", "Local node JSON file to diff against the base version, mutually exclusive with --compareVersion (exactly one required)")
             .option("--json", "Return the response as a JSON file")
             .action(this.diffNode);
 
@@ -311,7 +312,14 @@ class Module extends IModule {
     }
 
     private async diffNode(context: Context, command: Command, options: OptionValues): Promise<void> {
-        await new NodeDiffService(context).diff(options.packageKey, options.nodeKey, options.baseVersion, options.compareVersion, options.json);
+        if ((options.file && options.compareVersion) || (!options.file && !options.compareVersion)) {
+            throw new Error("Please provide either --compareVersion or --file, but not both.");
+        }
+        if (options.file) {
+            await new NodeDiffService(context).diffWithFile(options.packageKey, options.nodeKey, options.baseVersion, options.file, options.json);
+        } else {
+            await new NodeDiffService(context).diff(options.packageKey, options.nodeKey, options.baseVersion, options.compareVersion, options.json);
+        }
     }
 
     private async listNodeDependencies(context: Context, command: Command, options: OptionValues): Promise<void> {
diff --git a/src/commands/configuration-management/node-diff.service.ts b/src/commands/configuration-management/node-diff.service.ts
@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import { v4 as uuidv4 } from "uuid";
 import { logger } from "../../core/utils/logger";
 import { fileService, FileService } from "../../core/utils/file-service";
@@ -27,23 +28,52 @@ export class NodeDiffService {
         });
 
         if (jsonResponse) {
-            const filename = uuidv4() + ".json";
-            fileService.writeToFileWithGivenName(JSON.stringify(nodeDiff, null, 2), filename);
-            logger.info(FileService.fileDownloadedMessage + filename);
+            this.exportDiffAsJson(nodeDiff);
         } else {
-            logger.info(`Package Key: ${nodeDiff.packageKey}`);
-            logger.info(`Node Key: ${nodeDiff.nodeKey}`);
-            logger.info(`Name: ${nodeDiff.name}`);
-            logger.info(`Type: ${nodeDiff.type}`);
-            logger.info(`Is invalid configuration: ${nodeDiff.invalidContent}`);
-            if (nodeDiff.parentNodeKey) {
-                logger.info(`Parent Node Key: ${nodeDiff.parentNodeKey}`);
-            }
-            logger.info(`Change Date: ${new Date(nodeDiff.changeDate).toISOString()}`);
-            logger.info(`Updated By: ${nodeDiff.updatedBy}`);
-            logger.info(`Change Type: ${nodeDiff.changeType}`);
-            logger.info(`Changes: ${JSON.stringify(nodeDiff.changes)}`);
-            logger.info(`Metadata Changes: ${JSON.stringify(nodeDiff.metadataChanges)}`);
+            this.logDiff(nodeDiff);
         }
     }
+
+    public async diffWithFile(
+        packageKey: string,
+        nodeKey: string,
+        baseVersion: string,
+        file: string,
+        jsonResponse: boolean
+    ): Promise<void> {
+        const nodeDiff: NodeConfigurationDiffTransport = await this.nodeDiffApi.diffWithFile({
+            packageKey,
+            nodeKey,
+            baseVersion,
+            file: fs.createReadStream(file),
+        });
+
+        if (jsonResponse) {
+            this.exportDiffAsJson(nodeDiff);
+        } else {
+            this.logDiff(nodeDiff);
+        }
+    }
+
+    private exportDiffAsJson(nodeDiff: NodeConfigurationDiffTransport): void {
+        const filename = uuidv4() + ".json";
+        fileService.writeToFileWithGivenName(JSON.stringify(nodeDiff, null, 2), filename);
+        logger.info(FileService.fileDownloadedMessage + filename);
+    }
+
+    private logDiff(nodeDiff: NodeConfigurationDiffTransport): void {
+        logger.info(`Package Key: ${nodeDiff.packageKey}`);
+        logger.info(`Node Key: ${nodeDiff.nodeKey}`);
+        logger.info(`Name: ${nodeDiff.name}`);
+        logger.info(`Type: ${nodeDiff.type}`);
+        logger.info(`Is invalid configuration: ${nodeDiff.invalidContent}`);
+        if (nodeDiff.parentNodeKey) {
+            logger.info(`Parent Node Key: ${nodeDiff.parentNodeKey}`);
+        }
+        logger.info(`Change Date: ${new Date(nodeDiff.changeDate).toISOString()}`);
+        logger.info(`Updated By: ${nodeDiff.updatedBy}`);
+        logger.info(`Change Type: ${nodeDiff.changeType}`);
+        logger.info(`Changes: ${JSON.stringify(nodeDiff.changes)}`);
+        logger.info(`Metadata Changes: ${JSON.stringify(nodeDiff.metadataChanges)}`);
+    }
 }
diff --git a/tests/commands/configuration-management/config-node-diff.spec.ts b/tests/commands/configuration-management/config-node-diff.spec.ts
@@ -1,10 +1,17 @@
 import { NodeConfigurationDiffTransport } from "../../../src/commands/configuration-management/interfaces/node-diff.interfaces";
 import { NodeConfigurationChangeType } from "../../../src/commands/configuration-management/interfaces/diff-package.interfaces";
-import { mockAxiosGet } from "../../utls/http-requests-mock";
+import {
+    mockAxiosGet,
+    mockAxiosPost,
+    mockedAxiosInstance,
+    mockedPostRequestBodyByUrl,
+} from "../../utls/http-requests-mock";
 import { NodeDiffService } from "../../../src/commands/configuration-management/node-diff.service";
 import { testContext } from "../../utls/test-context";
 import { loggingTestTransport, mockWriteFileSync } from "../../jest.setup";
 import { FileService } from "../../../src/core/utils/file-service";
+import { mockCreateReadStream } from "../../utls/fs-mock-utils";
+import * as FormData from "form-data";
 import * as path from "path";
 
 describe("Node diff", () => {
@@ -290,4 +297,130 @@ describe("Node diff", () => {
         const changeDateLog = loggingTestTransport.logMessages.find(log => log.message.includes("Change Date:"));
         expect(changeDateLog.message).toContain(specificDate);
     });
+
+    it("Should throw a FatalError when the diff API call fails", async () => {
+        (mockedAxiosInstance.get as jest.Mock).mockRejectedValueOnce(new Error("network down"));
+
+        await expect(
+            new NodeDiffService(testContext).diff(packageKey, nodeKey, baseVersion, compareVersion, false)
+        ).rejects.toThrow(/Problem getting the node diff/);
+
+        expect(mockWriteFileSync).not.toHaveBeenCalled();
+    });
+
+    it("Should request the diff with both baseVersion and compareVersion query parameters", async () => {
+        const expectedUrl = `https://myTeam.celonis.cloud/pacman/api/core/packages/${packageKey}/nodes/${nodeKey}/diff/configuration?baseVersion=${baseVersion}&compareVersion=${compareVersion}`;
+        mockAxiosGet(expectedUrl, nodeDiff);
+
+        await new NodeDiffService(testContext).diff(packageKey, nodeKey, baseVersion, compareVersion, false);
+
+        expect(mockedAxiosInstance.get as jest.Mock).toHaveBeenCalledTimes(1);
+        const calledUrl = (mockedAxiosInstance.get as jest.Mock).mock.calls[0][0];
+        expect(calledUrl).toBe(expectedUrl);
+    });
+
+    describe("With file", () => {
+        const file = "./node.json";
+        const nodeJsonContent = Buffer.from(JSON.stringify({ key: nodeKey, configuration: { foo: "bar" } }));
+
+        beforeEach(() => {
+            mockCreateReadStream(nodeJsonContent);
+        });
+
+        it("Should diff a node file against STAGING and log all fields", async () => {
+            const url = `https://myTeam.celonis.cloud/pacman/api/core/packages/${packageKey}/nodes/${nodeKey}/diff/configuration/with-file?baseVersion=STAGING`;
+            mockAxiosPost(url, nodeDiff);
+
+            await new NodeDiffService(testContext).diffWithFile(packageKey, nodeKey, "STAGING", file, false);
+
+            expect(loggingTestTransport.logMessages.length).toBe(11);
+            expect(loggingTestTransport.logMessages[0].message.trim()).toEqual(`Package Key: ${nodeDiff.packageKey}`);
+            expect(loggingTestTransport.logMessages[1].message.trim()).toEqual(`Node Key: ${nodeDiff.nodeKey}`);
+            expect(loggingTestTransport.logMessages[2].message.trim()).toEqual(`Name: ${nodeDiff.name}`);
+            expect(loggingTestTransport.logMessages[3].message.trim()).toEqual(`Type: ${nodeDiff.type}`);
+            expect(loggingTestTransport.logMessages[4].message.trim()).toEqual(
+                `Is invalid configuration: ${nodeDiff.invalidContent}`
+            );
+            expect(loggingTestTransport.logMessages[5].message.trim()).toEqual(
+                `Parent Node Key: ${nodeDiff.parentNodeKey}`
+            );
+            expect(loggingTestTransport.logMessages[6].message.trim()).toEqual(`Change Date: ${nodeDiff.changeDate}`);
+            expect(loggingTestTransport.logMessages[7].message.trim()).toEqual(`Updated By: ${nodeDiff.updatedBy}`);
+            expect(loggingTestTransport.logMessages[8].message.trim()).toEqual(`Change Type: ${nodeDiff.changeType}`);
+            expect(loggingTestTransport.logMessages[9].message.trim()).toEqual(
+                `Changes: ${JSON.stringify(nodeDiff.changes)}`
+            );
+            expect(loggingTestTransport.logMessages[10].message.trim()).toEqual(
+                `Metadata Changes: ${JSON.stringify(nodeDiff.metadataChanges)}`
+            );
+        });
+
+        it("Should diff a node file against STAGING and return as JSON", async () => {
+            const url = `https://myTeam.celonis.cloud/pacman/api/core/packages/${packageKey}/nodes/${nodeKey}/diff/configuration/with-file?baseVersion=STAGING`;
+            mockAxiosPost(url, nodeDiff);
+
+            await new NodeDiffService(testContext).diffWithFile(packageKey, nodeKey, "STAGING", file, true);
+
+            const expectedFileName = loggingTestTransport.logMessages[0].message.split(
+                FileService.fileDownloadedMessage
+            )[1];
+
+            expect(mockWriteFileSync).toHaveBeenCalledWith(
+                path.resolve(process.cwd(), expectedFileName),
+                expect.any(String),
+                { encoding: "utf-8", mode: 0o600 }
+            );
+
+            const savedDiff = JSON.parse(mockWriteFileSync.mock.calls[0][1]) as NodeConfigurationDiffTransport;
+
+            expect(savedDiff.packageKey).toEqual(nodeDiff.packageKey);
+            expect(savedDiff.nodeKey).toEqual(nodeDiff.nodeKey);
+            expect(savedDiff.changeType).toEqual(nodeDiff.changeType);
+            expect(savedDiff.changes).toEqual(nodeDiff.changes);
+            expect(savedDiff.metadataChanges).toEqual(nodeDiff.metadataChanges);
+        });
+
+        it("Should diff a node file against a specific base version", async () => {
+            const specificBaseVersion = "1.0.0";
+            const url = `https://myTeam.celonis.cloud/pacman/api/core/packages/${packageKey}/nodes/${nodeKey}/diff/configuration/with-file?baseVersion=${specificBaseVersion}`;
+            mockAxiosPost(url, nodeDiff);
+
+            await new NodeDiffService(testContext).diffWithFile(packageKey, nodeKey, specificBaseVersion, file, false);
+
+            expect(loggingTestTransport.logMessages.length).toBe(11);
+            expect(loggingTestTransport.logMessages[0].message.trim()).toEqual(`Package Key: ${nodeDiff.packageKey}`);
+        });
+
+        it("Should send the node file as multipart/form-data with a 'file' field", async () => {
+            const url = `https://myTeam.celonis.cloud/pacman/api/core/packages/${packageKey}/nodes/${nodeKey}/diff/configuration/with-file?baseVersion=STAGING`;
+            mockAxiosPost(url, nodeDiff);
+
+            await new NodeDiffService(testContext).diffWithFile(packageKey, nodeKey, "STAGING", file, false);
+
+            const sentBody = mockedPostRequestBodyByUrl.get(url);
+            expect(sentBody).toBeInstanceOf(FormData);
+
+            const headers = (sentBody as FormData).getHeaders();
+            expect(headers["content-type"]).toMatch(/^multipart\/form-data; boundary=/);
+
+            // form-data keeps the registered parts in its internal `_streams` array. Each form
+            // field is represented by a header string followed by the value; assert that the
+            // header chunk for the 'file' field is present.
+            const streams: unknown[] = ((sentBody as unknown) as { _streams: unknown[] })._streams;
+            const fileFieldHeader = streams.find(
+                chunk => typeof chunk === "string" && chunk.includes('name="file"')
+            );
+            expect(fileFieldHeader).toBeDefined();
+        });
+
+        it("Should throw a FatalError when the diff-with-file API call fails", async () => {
+            (mockedAxiosInstance.post as jest.Mock).mockRejectedValueOnce(new Error("upload failed"));
+
+            await expect(
+                new NodeDiffService(testContext).diffWithFile(packageKey, nodeKey, "STAGING", file, false)
+            ).rejects.toThrow(/Problem getting the node diff/);
+
+            expect(mockWriteFileSync).not.toHaveBeenCalled();
+        });
+    });
 });
diff --git a/tests/commands/configuration-management/module.spec.ts b/tests/commands/configuration-management/module.spec.ts
