CALMHub Aware Difff

[LeighFinegold]

Feature Proposal

Target Project

CLI / Shared / CALM Hub integration

Primary targets:

• cli/
• shared/

Potential follow-on targets:

• calm-hub/
• calm-hub-ui/
• mcp

---

Description of Feature

Add first-class CALMHub-aware diff support to the CLI so users can compare a local CALM document against the version currently stored in CALMHub.

Today the existing calm diff command supports comparing two local CALM documents. However, there is no equivalent capability for comparing a local document against a document already published to CALMHub.

This creates a gap in the publication workflow because users cannot easily determine what semantic changes will be introduced by a publish operation.

Proposed Commands

Architecture

calm hub diff architecture [DOCUMENT] \
  --namespace <namespace> \
  --id <id> \
  --against latest|<version> \
  --summary

Pattern

calm hub diff pattern [DOCUMENT] \
  --namespace <namespace> \
  --id <id> \
  --against latest|<version> \
  --summary

Behaviour

The command should:

1. Retrieve the requested CALMHub document version.
2. Run the existing semantic CALM diff engine (calm cli diff)
3. Compare the retrieved document against the local document.
4. Present results using the same output format and exit-code behaviour as the existing calm diff command.

---

Background

A common publishing workflow is:

1. A CALM document exists in CALMHub.
2. A user makes changes locally in source control.
3. The changes are reviewed through a Pull Request.
4. The updated document is published to CALMHub.

Before publishing, users often need to answer:

What semantic CALM changes will be introduced if this document is published?

Currently there is no direct way to answer this question without manually downloading the existing CALMHub version and invoking calm diff separately.

---

Related Concern: No-op Publishing

A related publish-safety concern is that calm hub push can currently create a new version even when the local document is semantically identical to the latest version already stored in CALMHub.

This feature would enable build pipelines and release processes to detect:

• no-op publishes
• accidental version churn
• unexpected semantic changes

Future enhancements could optionally introduce pre-flight validation in calm hub push to prevent publishing when no semantic changes are detected.

However, the proposed calm hub diff command is the preferred first step because it is:

• read-only
• composable
• CI-friendly
• useful independently of any publishing workflow

---

User Stories

Story 1

As an architecture owner, I want to compare my local CALM document against the latest CALMHub version so that I can understand what semantic changes will be published.

Story 2

As a release engineer, I want to use semantic diff information in CI/CD pipelines so that I can validate changes before publishing to CALMHub.

Story 3

As a CALMHub administrator, I want to identify when a publish operation would create an identical version so that unnecessary versions are not created.

Acceptance Criteria

• A user can compare a local architecture document against a CALMHub version.
• A user can compare a local pattern against a CALMHub version.
• The command uses the existing semantic diff engine.
• Output formatting is consistent with calm diff.
• The command supports comparison against the latest version.
• The command supports comparison against a specific version.
• The command is suitable for automation and CI/CD usage.