feat(migration): seed Exa pre-install from EXA_API_KEY env var

[FelixMalfait]

Summary

One-shot bridge for instances that set EXA_API_KEY as an env var under the old native web-search driver (removed in #19980). Prevents a gap between deploy and admin setup where Exa search is broken.

Stacked on top of #19980 — depends on the isPreInstalled column + the twenty-exa npm package.

What it does

A slow instance command that runs at deploy time:

1. Skips if EXA_API_KEY is unset → no-op on fresh instances.
2. Fetches the twenty-exa manifest from the app registry CDN and upserts the ApplicationRegistration via the existing catalog-sync path.
3. Seeds EXA_API_KEY onto the registration's server variable, encrypted via SecretEncryptionService. Never overwrites a value already edited through the admin UI.
4. Flips isPreInstalled=true. New workspaces auto-install from that point; existing workspaces are backfilled with the install-pre-installed-apps CLI command.

Idempotent — each step no-ops when its target already exists. Safe to rerun.

Prerequisites

Before merging / deploying:

1. Publish twenty-sdk@2.1.0 (new ./billing subpath, introduced in feat(app): migrate Exa web search to a pre-installed app #19980).
2. Publish twenty-exa@0.1.0 to npm.

Otherwise the migration's CDN fetch returns no manifest and the command logs a warning and exits clean (no crash).

Post-deploy

• Drop EXA_API_KEY from infra env vars — it now lives encrypted on the registration.
• Run npx nx run twenty-server:command install-pre-installed-apps to backfill existing workspaces (new workspaces pick it up automatically).

Why a separate PR

Keeps #19980 focused on the architectural migration. This one is a deployment-lifecycle helper — reviewable in isolation and droppable without losing the core work if we change our mind on the bridging strategy.

Test plan

• Unit tests for the command
• Verify server boots with new command registered (✅ Registered 1 fast instance, 1 slow instance ... for 2.0.0)
• Verify idempotency: run migration twice against a seeded instance
• Verify no-op when env var absent
• Verify no-op when registration already exists with isPreInstalled=true

🤖 Generated with Claude Code

[twenty-ci-bot-public]

🚀 Preview Environment Ready!

Your preview environment is available at: http://bore.pub:63089

This environment will automatically shut down after 5 hours.

[prastoin]

@claude could you please review this PR ?

[claude]

Claude finished @prastoin's task in 3m 52s —— View job

---

Claude PR Review

• Read the migration command (slow instance command)
• Read the fast instance command (add isPreInstalled column)
• Review the install-pre-installed-apps CLI command
• Review pre-installed-apps service
• Review app-billing controller/service
• Check entity changes (ApplicationRegistration)
• Review logic-function-executor changes
• Inspect related infrastructure (encryption, marketplace sync)
• Post review feedback

Summary

Tightly scoped, well-considered bridge migration. The data flow is clean: env var → catalog upsert → server variable seed → isPreInstalled flip → backfill via CLI. Idempotency is handled correctly at every step. The feature flag for === '' / !isPreInstalled matches existing canonical patterns (isFilled getter on ApplicationRegistrationVariableEntity:53 uses the same !== '' convention).

Findings

1. Silent skip when the manifest doesn't declare EXA_API_KEY — 2-0-instance-command-slow-...seed-exa-pre-install-from-env.ts:106-118

const variable = await this.applicationRegistrationVariableRepository.findOne({
  where: { applicationRegistrationId: registration.id, key: 'EXA_API_KEY' },
});

if (variable && variable.encryptedValue === '') {
  await this.applicationRegistrationVariableRepository.update(...)
}

If a future published twenty-exa version drops EXA_API_KEY from serverVariables, syncVariableSchemas won't create the row, findOne returns null, the env-var seed is silently dropped, and the migration still flips isPreInstalled=true. The local manifest at packages/twenty-apps/internal/exa/src/application.config.ts:16-23 declares it correctly today — but the migration fetches the published manifest from the CDN, so this is a soft coupling that's invisible if it ever breaks.

Recommendation: when variable is null after upsertFromCatalog, log a warn so operators notice instead of silently leaving a half-seeded install.

Fix this →

2. No unit tests for the slow command

The PR's own test plan still has all four items unchecked. The command has six branches worth covering: no env, no package, no manifest, registration-missing-after-upsert, variable-empty-vs-filled, isPreInstalled-already-true. All can be tested with mocked MarketplaceService and repos. Worth adding before merge — the PR description bills idempotency and no-op semantics as the load-bearing guarantees.

3. installApplication with no version pin during backfill — pre-installed-apps.service.ts:34-37

await this.applicationInstallService.installApplication({
  appRegistrationId: registration.id,
  workspaceId,
});

No version is passed, so resolvePackage will pick the latest. That's the intended behavior, but worth confirming: if latestAvailableVersion advances between the migration run and the CLI backfill, different workspaces could end up on different versions if the backfill is run incrementally. Probably acceptable for a pre-install scenario but worth being aware of.

4. down migration is a no-op for runDataMigration

Lines 42-44 of the slow command leave up and down empty (correct — the schema column is in the fast command), and runDataMigration has no inverse. This is normal for data migrations, but the encrypted seeded value will persist after a down. Not really fixable here, just a note: a true rollback would need to manually clear the variable row.

5. AppBillingController charge endpoint — app-billing.controller.ts:33-77

Solid security posture: triple-guarded (Jwt + WorkspaceAuth + NoPermission), enforces application-access tokens (rejects user/api-key tokens), throttles per (workspace, application) pair, validates body via DTO with sane bounds (MAX_CREDITS_USED_MICRO_PER_CHARGE = $1000, MAX_QUANTITY_PER_CHARGE = 10_000).

Two minor observations:

• IS_BILLING_ENABLED=false returns 404 — unusual versus 403, but it does avoid leaking the existence of the endpoint to community instances. Consistent with how feature gating is done elsewhere, so probably intentional.
• emitChargeEvent returns synchronously while the usage event is fire-and-forget. Matches existing ai-billing.service.ts pattern, so consistent.

6. SDK chargeCredits silently no-ops when env vars missing — twenty-sdk/src/sdk/billing/charge-credits.ts:27-32

if (!apiUrl || !token) {
  return;
}

Documented as intentional for local/test runs. Worth noting that this also means a production app misconfigured (e.g. token not propagated through the runtime) silently won't be billed. The console.error on non-OK responses helps, but a missing-env-var case is invisible. Consider a one-time console.warn so misconfig is at least audit-detectable from app logs.

7. EXA_PACKAGE_NAME hardcoded as a top-level constant — fine

Hardcoded twenty-exa is the right call here — this is intentionally a one-shot bridge for one specific package. No abstraction needed.

8. process.env.EXA_API_KEY direct read instead of TwentyConfigService — fine

The env var was removed from config-variables.ts (line 0/-21) so it's no longer a "known" config. Reading directly is the right call for a deprecated transition variable.

9. Style consistency — 2-0-instance-command-slow-...:42-46

up/down are declared public async while runDataMigration is just async. Tiny nit — pick one.

Verdict

The migration logic is sound, idempotent, and the rollout path (publish package → deploy → run CLI backfill → drop env var) is documented. The two things I'd want before merge:

1. Add a warn log when the registration's EXA_API_KEY variable row is missing after upsert (defends against published-manifest drift).
2. Land the unit tests the test plan promises — the branch matrix is small but load-bearing.

Everything else is observation, not blocker.
· branch: feat/exa-seed-pre-install-from-env