feat(BEX-290): add UI app support for action links

[piyushsarin-sib]

What

Adds a second app type alongside OAuth integrations. A UI app shares the app record, credentials, and version lifecycle with an OAuth app, and adds a ui_app block to app-config.json describing where and how it renders inside Brevo. The first variant is the action link: an entry in a CRM record's header More menu that opens an external URL with record context.

Based on features_set_public_cli, not main — this extends applyConditionals, which the PKCE work introduced on that branch.

Two commits: the initial implementation, then a refactor! aligning the contract with the platform (see Contract below).

Contract — verified against the platform

The ui_app block is the app-store backend's app_versions.snapshot payload field for field, so an authored config needs no translation to be stored, served and rendered:

{
  "ui_app": {
    "extensionType": "action_link",
    "surfacePointList": ["contactDetails.headerMenu.action"],
    "heading": "Invoice Manager",
    "subheading": "Review invoice history for this contact",
    "redirectLink": "https://example.com/brevo",
    "linkTarget": "_blank"
  }
}

Verified against appSnapshot in app-store-backend feature/BEX-308-extensibility-app-configs and ActionLinkConfig / getExtensionActions in integrations-common-frontend bex-350-app-configs-link-target. The second commit replaced an earlier draft that followed the product spec's properties/trigger vocabulary — which nothing on either side of the platform reads.

Two spec'd fields are deliberately absent, because the platform has no counterpart:

• a per-action label — the menu entry is labelled with the app name (getExtensionActions uses app.appName);
• contextProperties — the record context an action receives is an allow-list on the extension_points registry row (AllowedContextField), chosen per slot by the platform, not declared by the partner.

Command surface

Change	Detail
app create --type <oauth|ui>	New flag plus a leading app-type prompt. Defaults to oauth; non-interactive runs without the flag are unchanged.
UI-app flags	Repeatable --surface <contact|company|deal>, --heading, --subheading, --redirect-link, --link-target <_blank|_self>. Every prompt has a scriptable equivalent.
app deploy <account-id>	Make an app available in one account. Refuses until the config has been validated by app upload.
app remove <account-id>	Remove it from one account. No upload gate; "not deployed" exits 0.

Notable behaviour

• Extension-point names are validated locally against the twelve-point registry. This is the highest-value check in the flow. Slot names follow the BEX-350 grammar <location>.<place>.<kind>; the UI kit matches them by exact string equality and the backend drops any name without a registry row. A typo, a stale .region-era name, or a casing slip therefore produces an empty slot, an HTTP 200, and no error anywhere in the stack — the CLI is the only layer that can report it. An action link may only target <location>.headerMenu.action; a .widget slot is rejected.
• modalIframeUrl is rejected on an action link — the UI kit keeps it only for iframe_extension, so authoring one here would be silently discarded.
• The UI path never collects or defaults a redirect URL. resolveRedirectUrls falls back to http://localhost:3009/auth/callback in non-TTY runs, so without an explicit skip a UI app would acquire a callback it has no flow for. redirect_uris is omitted from the create call entirely.
• The redirect-URL requirement on app upload is now OAuth-only.
• The upload diff covers the snapshot. Previously hasNoChanges compared every field except this one, so editing only ui_app would report "Already up to date" and never push. Comparison is key-order insensitive.
• app scaffold no longer destroys a hand-edited ui_app block. On detected drift it rewrites app-config.json wholesale from server values, which don't include it.
• The app type is decided locally, never from server data. fetchAppContext takes the block from its caller only — honouring a server-returned snapshot could reclassify a project explicitly created as OAuth. Regression test included.
• applyConditionals generalised from a single distribution value to a flag set, preserving its byte-for-byte output invariant for existing scaffolds.

Inverted contract — please note in review

upload.test.ts previously asserted it('never sends a ui_app field'), and QA-TESTCASES.md TC-5.7 said the same. That guarantee now applies to OAuth apps only; both were updated rather than deleted. The OAuth upload payload is otherwise unchanged and still never carries the key.

What still needs confirming

The field names are settled. What isn't:

1. The snapshot write path doesn't exist yet. On the BEX-308 branch only the manifest read path parses app_versions.snapshot; app-store-bo-be's POST /apps/{appId}/build writes the separate config column via a multipart config field. The CLI currently sends the block under a snapshot key on POST /v3/app-store/apps/{id}/upload — needs confirming or correcting once the write endpoint lands. src/types.ts (UploadAppPayload) and upload.ts are the only places to change.
2. Deploy/remove endpoints assume POST /v3/app-store/apps/{id}/deploy|remove with account_id in the body, and HTTP 422 for "not uploaded" / "not deployed".
3. BEX-350 needs a coordinated release — kit, reseeded extension_points registry, and backend together. A CLI release ahead of the reseed authors names that resolve to nothing, silently. The CLI's registry copy lives in src/lib/constants.ts (EXTENSION_POINTS) and must move in lockstep.

Tracked in RELEASE-CHECKLIST.md → Before UI-apps GA.

Testing

• yarn test — 847 passing (46 suites). New: deploy.test.ts, remove.test.ts, plus UI-app blocks in create/upload/scaffold/validators/conditionals, including a case per silent-failure slot-name mode.
• yarn lint, tsc --noEmit, prettier --check clean.
• Manually driven end to end against a mock API: UI-app create → config inspection → upload (payload key confirmed as snapshot) → deploy → remove; each validation rejection; the deploy gate; the snapshot-only diff; and an OAuth regression sweep confirming an unchanged config and payload.
• Manual verification still outstanding against a real test account — see RELEASE-CHECKLIST.md → Per-branch verification. In particular whether the backend accepts the snapshot, and whether the action link renders once the registry is reseeded.

Docs

Design notes are committed at BEX-290-ui-app-action-links.md — the contract, which changes were forced by existing code, and what's still assumed. A third commit sanitised internal references (private repo/branch names, source paths, internal symbols, DB schema, a partner name) out of both those notes and the code comments added alongside them, replacing them with the platform roles the CLI depends on plus the Jira keys. Nothing load-bearing was lost — the wire contract, slot grammar, registry and validation rules are all partner-facing and already in the shipped agent-context files.

agent-context/SKILL.md and agent-context/AGENTS.md both updated and kept in sync per CLAUDE.md — new commands, flags, the snapshot shape, the slot grammar and its silent-failure modes, and the fields that don't exist. Both carry a ⚠️ UI apps are not available yet notice mirroring the public-apps one, reusing the same internal-Brevo-account exception so dogfooding still works — flagging this as a judgement call, easy to drop if unwanted. Also updated: README.md (including a stale brevo app update row that predates this change), CLAUDE.md, root AGENTS.md, QA-TESTCASES.md (section 12, 14 cases), RELEASE-CHECKLIST.md, TODO.md, and a changeset (minor).

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.6% Duplication on New Code

See analysis details on SonarQube Cloud