[Comunity Goal 2026] [S1] Migrate `@asyncapi/diff` into the CLI

[princerajpoot20]

Description

We have approval from the codeowners of diff and cli.
More details here:
asyncapi/diff#226
#2251

We are proceeding with the merger.

Migrate @asyncapi/diff into asyncapi/cli as packages/diff/.

We will assess whether any changes are needed so the library fits the CLI repo. If a breaking change is needed, we will bump the major version. We did this for @asyncapi/optimizer when it moved into CLI, so it could align with how the CLI works.

Action items

• Move code into cli (packages/diff/)
• Update turbo.json / monorepo wiring for the new package
• Point root CLI dependency at the workspace package (today "@asyncapi/diff": "^0.5.0")
• Update repo-related details in the diff package.json (repository URL and other related fields as needed)
• Merge CODEOWNERS into cli
• Add a spec for diff (see below)
• Update other relevant files as needed, such as the README and architecture docs
• Sanity check the diff repo and its code. Explore it and note anything else we should be aware of before/during the move
• Assess and identify any changes needed so diff aligns with the CLI repo. If a breaking change is needed, bump the major version (same as optimizer)
• Update the CLI diff command and server-api /diff so they use the workspace package after the move
• Update the test pipeline so the diff package tests run in cli, and check that existing CLI diff and server-api tests still pass
• Sort out releases so @asyncapi/diff publishes from cli (update the release pipeline so it can release diff)
• Make the npm changes: update relevant fields, add/update the trusted publisher in NPM, and check NPM portal settings
• Test the release

Out of scope: Archiving the diff repo.

Spec

The reason we are consolidating these repos and the broader community goal of auditing, is to improve repo health and maintainability, bring on more maintainers, and eventually reduce maintainer burnout.

As part of that, we are adding specs in these repos. Specs act as a source of truth for contributors, and more importantly give AI context about the package. That should help anyone developing here, whatever approach they follow: pure vibe coding, pure spec-driven, or a mix of both.

Notes on references inside cli

What does need updating: root package.json currently has "@asyncapi/diff": "^0.5.0" (npm). After migration it should use the local workspace package, so builds/tests resolve to packages/diff instead of registry.npmjs.org.

The CLI diff command currently imports from @asyncapi/diff/lib/asyncapidiff. After the move, use the normal package export instead.

cli/openapi.yaml is the API spec for the CLI's server-api (it documents a /diff endpoint). It currently links to the standalone asyncapi/diff GitHub repo. Update that link, and other docs/README links, to the monorepo path.

Check Docker and the GitHub Action image. If they need changes for diff.

The CLI has a shared output / error-code convention. Assess how diff (the library and the asyncapi diff command) should follow that, same as we did for optimizer.

References

• https://github.com/asyncapi/diff
• https://github.com/asyncapi/cli
• Prior art: [Community Goal 2026] [S1] Move optimizer into the CLI optimizer#306
• Prior art: [Community Goal 2026] [S1] Migrate @asyncapi/openapi-schema-parser into the parser-js openapi-schema-parser#326

[princerajpoot20]

I will be working on this.

[princerajpoot20]

Reason for the Advanced Classification

The Advanced Classification is required because of the following list of work that needs to be completed in order to resolve this issue:

• Move the entire codebase with changes. Check action item list for more details on this.
• Assess and identify any changes needed so the library aligns with CLI. If a breaking change is needed, bump the major version (same as optimizer).
• Make sure the migrated code follows the CLI shared output / error-code convention where needed (same as optimizer).
• Wire the package into the existing CLI monorepo (Turbo / workspaces).
• Update the test pipeline so the diff package tests run in cli, and check that existing CLI diff and server-api tests still pass.
• Sort out the release from cli (update the release pipeline so it can release diff), and make the NPM changes (trusted publisher and portal settings).
• Test the release.
• Update the documentation and other references, such as package.json.
• Add specs for diff.