fix(workflows): preserve comparison semantics and preview ports

Author: icecrasher321

.github/workflows/test-build.yml

@@ -201,7 +201,7 @@ jobs:
           if-no-files-found: ignore
           retention-days: 7
 
-      - name: Verify SCIM and administration over real HTTP
+      - name: Verify SCIM, administration and workflow comparisons over real HTTP
         working-directory: apps/sim
         env:
           NEXT_PUBLIC_APP_URL: http://127.0.0.1:3017
@@ -249,14 +249,20 @@ jobs:
           SCIM_E2E_AUTH_SECRET="$BETTER_AUTH_SECRET" \
           SCIM_E2E_REPORT_PATH="$RUNNER_TEMP/scim-e2e-report.json" \
             bun run test:scim:e2e
+          VERSION_COMPARE_E2E_BASE_URL="$NEXT_PUBLIC_APP_URL" \
+          VERSION_COMPARE_E2E_DATABASE_URL="$DATABASE_URL" \
+          VERSION_COMPARE_E2E_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+          VERSION_COMPARE_E2E_REPORT_PATH="$RUNNER_TEMP/version-compare-http-report.json" \
+            bun run test:workflow-version-compare:e2e
 
-      - name: Upload SCIM failure report and HTTP status log
+      - name: Upload HTTP acceptance failure reports and status log
         if: failure()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: scim-failure-${{ matrix.provision }}
           path: |
             ${{ runner.temp }}/scim-e2e-report.json
+            ${{ runner.temp }}/version-compare-http-report.json
             ${{ runner.temp }}/scim-http-status.log
           if-no-files-found: ignore
           retention-days: 7

apps/docs/openapi-v2-workflows.json

@@ -1204,7 +1204,7 @@
       "get": {
         "operationId": "compareWorkflowVersionsV2",
         "summary": "Compare Workflow Versions",
-        "description": "Compare two deployment versions of the same workflow. Reports semantic changes, excluding canvas layout; credential-bearing values are withheld while their changes remain visible. The combined snapshots must fit within 16 MiB.\n\nOAuth scope: `api:read`.",
+        "description": "Compare two deployment versions of the same workflow. Reports semantic changes, excluding canvas layout; credential-bearing values are withheld while their changes remain visible. Connections include stable block and port identifiers. The combined snapshots and the comparison result must each fit within 16 MiB.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.versions.compare",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -9480,6 +9480,22 @@
                     "items": {
                       "type": "object",
                       "properties": {
+                        "source": {
+                          "type": "string",
+                          "description": "Stable source block identifier."
+                        },
+                        "target": {
+                          "type": "string",
+                          "description": "Stable target block identifier."
+                        },
+                        "sourceHandle": {
+                          "description": "Source port identifier; omitted for the default port.",
+                          "type": "string"
+                        },
+                        "targetHandle": {
+                          "description": "Target port identifier; omitted for the default port.",
+                          "type": "string"
+                        },
                         "sourceName": {
                           "type": "string",
                           "description": "Source block name."
@@ -9489,7 +9505,7 @@
                           "description": "Target block name."
                         }
                       },
-                      "required": ["sourceName", "targetName"],
+                      "required": ["source", "target", "sourceName", "targetName"],
                       "additionalProperties": false
                     },
                     "description": "Added connections."
@@ -9499,6 +9515,22 @@
                     "items": {
                       "type": "object",
                       "properties": {
+                        "source": {
+                          "type": "string",
+                          "description": "Stable source block identifier."
+                        },
+                        "target": {
+                          "type": "string",
+                          "description": "Stable target block identifier."
+                        },
+                        "sourceHandle": {
+                          "description": "Source port identifier; omitted for the default port.",
+                          "type": "string"
+                        },
+                        "targetHandle": {
+                          "description": "Target port identifier; omitted for the default port.",
+                          "type": "string"
+                        },
                         "sourceName": {
                           "type": "string",
                           "description": "Source block name."
@@ -9508,7 +9540,7 @@
                           "description": "Target block name."
                         }
                       },
-                      "required": ["sourceName", "targetName"],
+                      "required": ["source", "target", "sourceName", "targetName"],
                       "additionalProperties": false
                     },
                     "description": "Removed connections."

apps/sim/app/api/workflows/[id]/deployments/[version]/route.ts

@@ -49,6 +49,7 @@ export const GET = defineInternalJsonRoute({
     workflowId: params.id,
     version: params.version,
     includeCredentialValues: true,
+    representation: 'comparison' as const,
   }),
   present: ({ version }) => ({ deployedState: version.state }),
 })