CEXT-6509 Manage Admin UI Component Additions and Removals During Application Upgrade

[vinayrao2000]

Description

Adds upgrade plan/apply support to the Admin UI domain so that application upgrades (not just fresh installs/uninstalls) reconcile the registered Admin UI extension to match the target configuration.

planAdminUi diffs the installed baseline against the target config component-by-component — the top-level menu, per-entity gridColumns, per-id massActions, and order viewButtons — emitting one add/remove operation per component that appeared or disappeared. Because Commerce registers the extension as a single unit (no per-component API), the operations collapse to one whole-extension AdminUiExtensionAction on the plan:

• Component added (block newly declared) → register (enable SDK → register).
• Component added/removed while the block persists → refresh (re-register to re-sync from the App Registry).
• All Admin UI removed → unregister (validated, 404-tolerant DELETE).

Also includes: a strict unregisterExtensionForUpgrade for the upgrade removal path (throws on any non-404 failure, treats 404 as already-removed), a refreshExtension wrapper (interim re-POST until CEXT-6559's /refresh ships), and a graceful blocked result when the runtime namespace is unavailable rather than throwing and crashing the planning pass.

Related Issue

CEXT-6509 — Manage Admin UI Component Additions and Removals During Application Upgrade.

Motivation and Context

The Admin UI domain could install and uninstall an app's extension, but an upgrade had no way to reconcile Admin UI state when the config changed between versions. A developer who added a menu entry, dropped an order-grid column, or added a mass action in a new app version would leave the merchant with an admin that no longer matches the deployed code. This change makes upgrades converge the registered extension to exactly match the target config, as a sibling of the merged webhooks upgrade (#621) and the in-flight eventing upgrade (#624).

How Has This Been Tested?

• Unit tests (Vitest) covering every path at the plan and apply layers:
  • plan: register / refresh / unregister classification, per-component add/remove detection, modification-skip (no op for a component changed on both sides), empty-block no-op, duplicate-id disambiguation, and a blocked result when __OW_NAMESPACE is unavailable.
  • apply: enable-then-register on register, re-register on refresh, strict unregister (throws on non-404, tolerates 404), no-op, and cleanup-resource reuse from the plan.
• Full package suite green (pnpm --filter @adobe/aio-commerce-lib-app test), typecheck clean, lint (Biome + Redocly) clean.
• Manual E2E against a live Stage Commerce instance (self-deployed app), covering the full matrix:
  • modify a column inside gridColumns → correctly skipped (no change);
  • drop order.gridColumns → columns removed via refresh;
  • restore order.gridColumns → columns re-added via refresh;
  • drop the whole adminUi block → extension unregistered (menu + columns gone);
  • re-add the block → registered fresh;
  • add product.gridColumns (multi-entity) and an order massAction (array component) → both appeared;

Screenshots (if appropriate):

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have read the DEVELOPMENT document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: a8ecc56

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@adobe/aio-commerce-lib-admin-ui	Minor
@adobe/aio-commerce-lib-app	Minor
@adobe/aio-commerce-sdk	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[iivvaannxx]

I'm checking plan and apply logic but maybe you can act on the below comments now

[iivvaannxx]

An empty adminUi block should be treated the same as no Admin UI config. Then we can base register/unregister on whether components exist and drop the synthetic extension component.

Probably you can fix install requiring at least a component before running, seems it's a related concern.

This PR works around a lot, trying to respect that when it's not very correct IMO.