Skip to content

feat: add translation-companion app for unattended CMA [TRANS-287] - #11262

Draft
Adrian Meyer (primeinteger) wants to merge 1 commit into
masterfrom
TRANS-287
Draft

feat: add translation-companion app for unattended CMA [TRANS-287]#11262
Adrian Meyer (primeinteger) wants to merge 1 commit into
masterfrom
TRANS-287

Conversation

@primeinteger

@primeinteger Adrian Meyer (primeinteger) commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Purpose

TRANS-287's webhook consumer and reconciliation job need to call the CMA with no user token in the loop. This adds a minimal Contentful app whose only job is to hold an App Identity that unblocks that.

Ticket: TRANS-287

Approach

  • Standalone Standard Vite app (apps/translation-companion) with a single ConfigScreen location, no App Actions/Functions/Lambda. Its only job is to exist as an installed App Definition, so that installation carries an App Identity.
  • App Identity/App Keys/scopes and the AppInstallation are provisioned manually and out-of-band -- the App Definition's Security/Permissions tabs, plus the same generic provisioning scripts every other app in this repo already uses.
  • A consuming service (e.g. translation-api) does all JWT signing and CMA calls itself, using the private key handed off via Secrets Manager -- the same pattern apps/netlify already uses. This app never touches the private key at runtime.
  • Scoped and named generically rather than to a single feature, so future translation product unattended-access needs can reuse this App Definition instead of provisioning new ones. Full rationale (alternatives considered, why this shape) is in docs/ADRs/0001-app-identity-for-unattended-cma-access.md.

Testing steps

  1. cd apps/translation-companion && npm install
  2. npm run lint && npm run test:ci && npm run build -- all should pass clean.
  3. npm start and confirm the ConfigScreen renders, calls sdk.app.setReady(), and shows the "Uninstall warning" note.
  4. Full end-to-end verification (minting an App Access Token with no user token in the flow) requires the App Definition to actually exist -- see Deployment below. That step isn't exercised by this PR's code, since App Identity/App Keys/scopes/install are all provisioned out-of-band, not through this app.

Breaking Changes

None. This is a net-new, isolated app package; it doesn't touch any other app, shared package, or root-level tooling.

Dependencies and/or References

  • apps/translation-companion/docs/ADRs/0001-app-identity-for-unattended-cma-access.md in this PR -- full rationale for App Identity over delegated tokens or App Functions.
  • Prior art in this repo: apps/netlify (existing App Identity/getManagementToken() pattern), apps/remote-mcp and apps/homebase (Standard Vite App scaffold this mirrors).

Deployment

  • The App Definition does not exist yet. package.json's deploy/deploy:test scripts have placeholder --definition-id values (REPLACE_WITH_PRODUCTION_APP_DEFINITION_ID/REPLACE_WITH_TEST_APP_DEFINITION_ID) that must be filled in once scripts/actions/createAppDefinition.ts is run against a real org -- CI deploy will fail until then.
  • App Keys and CMA scopes are generated/granted manually via the App Definition's Security and Permissions tabs (see AGENTS.md), and the AppInstallation is created per space + environment via scripts/actions/installApp.ts. None of this is automated by this PR.
  • No consuming service can use this app's identity until the private key is handed off through AWS Secrets Manager after key generation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant