N+1 UPDATE queries in refresh token suspicious activity detection

https://sonarly.com/issue/3877?type=bug

The suspicious activity detection in RefreshTokenService.verifyRefreshToken() fires N individual UPDATE queries (one per user token) instead of a single bulk UPDATE when revoking all tokens, causing ~600 DB round-trips and ~2.9 seconds of cumulative DB time for users with many accumulated tokens.

Fix: ## Root cause

`verifyRefreshToken()` in `refresh-token.service.ts` was triggering the suspicious-activity path by iterating over every `AppTokenEntity` for a user and firing one `UPDATE` per row, producing ~600 individual SQL statements for a user who had accumulated many tokens:

```typescript
// BEFORE (N+1)
await Promise.all(
  user.appTokens.map(async ({ id, type }) => {
    if (type === AppTokenType.RefreshToken) {
      await this.appTokenRepository.update({ id }, { revokedAt: new Date() });
    }
  }),
);
```

## Fix

Replace the N+1 loop with a single bulk `UPDATE` — exactly the same pattern already used in `auth.service.ts` — and remove the now-unnecessary `relations: ['appTokens']` eager-load from the `userRepository.findOne()` call:

```typescript file=packages/twenty-server/src/engine/core-modules/auth/token/services/refresh-token.service.ts lines=70-95
// User fetch no longer needs to load the full token list
const user = await this.userRepository.findOne({
  where: { id: jwtPayload.sub },
});
// …
// AFTER: single bulk UPDATE regardless of token count
await this.appTokenRepository.update(
  {
    userId: user.id,
    type: AppTokenType.RefreshToken,
    revokedAt: IsNull(),
  },
  { revokedAt: new Date() },
);
```

`IsNull()` is imported from `typeorm` (added to the existing import line) and ensures only currently-active (non-revoked) tokens are touched, matching the semantics of the original loop's `if (type === AppTokenType.RefreshToken)` filter while collapsing all work into one SQL statement:

```sql
UPDATE core."appToken"
SET "revokedAt" = $1, "updatedAt" = CURRENT_TIMESTAMP
WHERE "userId" = $2
  AND "type" = 'REFRESH_TOKEN'
  AND "revokedAt" IS NULL
```

This reduces ~600 round-trips (~2.9 s of cumulative DB time) to a single query for any user regardless of how many accumulated tokens they have.

.github/actions/spawn-twenty-docker-image/action.yaml

@@ -0,0 +1,80 @@
+name: Spawn Twenty Docker Image
+description: >
+  Starts a full Twenty instance (server, worker, database, redis) using Docker
+  Compose. The server is available at http://localhost:3000 for subsequent steps
+  in the caller's job.
+  Pulls the specified semver image tag from Docker Hub.
+  Designed to be consumed from external repositories (e.g., twenty-app).
+
+inputs:
+  twenty-version:
+    description: 'Twenty Docker Hub image tag as semver (e.g., v0.40.0, v1.0.0).'
+    required: true
+  twenty-repository:
+    description: 'Twenty repository to checkout docker compose files from.'
+    required: false
+    default: 'twentyhq/twenty'
+  github-token:
+    description: 'GitHub token for cross-repo checkout. Required when calling from an external repository.'
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  server-url:
+    description: 'URL where the Twenty server can be reached'
+    value: http://localhost:3000
+  access-token:
+    description: 'Admin access token for the Twenty instance'
+    value: ${{ steps.admin-token.outputs.access-token }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Validate version
+      shell: bash
+      run: |
+        VERSION="${{ inputs.twenty-version }}"
+        if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+          echo "::error::twenty-version must be a semver tag (e.g., v0.40.0). Got: '$VERSION'"
+          exit 1
+        fi
+
+    - name: Checkout docker compose files
+      uses: actions/checkout@v4
+      with:
+        repository: ${{ inputs.twenty-repository }}
+        ref: ${{ inputs.twenty-version }}
+        token: ${{ inputs.github-token }}
+        sparse-checkout: |
+          packages/twenty-docker
+        sparse-checkout-cone-mode: false
+        path: .twenty-spawn
+
+    - name: Prepare environment
+      shell: bash
+      working-directory: ./.twenty-spawn/packages/twenty-docker
+      run: |
+        cp .env.example .env
+        echo "" >> .env
+        echo "TAG=${{ inputs.twenty-version }}" >> .env
+        echo "APP_SECRET=replace_me_with_a_random_string" >> .env
+        echo "SERVER_URL=http://localhost:3000" >> .env
+
+    - name: Start Twenty instance
+      shell: bash
+      working-directory: ./.twenty-spawn/packages/twenty-docker
+      run: |
+        docker compose up -d --wait || {
+          echo "::error::Docker compose failed to start or health checks timed out"
+          docker compose logs
+          exit 1
+        }
+        echo "Twenty instance is ready at http://localhost:3000"
+
+    - name: Set admin access token
+      id: admin-token
+      shell: bash
+      run: |
+        ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik"
+        echo "::add-mask::$ACCESS_TOKEN"
+        echo "access-token=$ACCESS_TOKEN" >> "$GITHUB_OUTPUT"

.github/workflows/cd-deploy-main.yaml

@@ -11,7 +11,7 @@ on:
 jobs:
   deploy-main:
     timeout-minutes: 3
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Repository Dispatch
         uses: peter-evans/repository-dispatch@v2

.github/workflows/cd-deploy-tag.yaml

@@ -11,7 +11,7 @@ on:
 jobs:
   deploy-tag:
     timeout-minutes: 3
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Repository Dispatch
         uses: peter-evans/repository-dispatch@v2

.github/workflows/changed-files.yaml

@@ -16,7 +16,7 @@ permissions:
 jobs:
   changed-files:
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     outputs:
       any_changed: ${{ steps.changed-files.outputs.any_changed }}
     steps:

.github/workflows/ci-breaking-changes.yaml

@@ -32,7 +32,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 45
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo

.github/workflows/ci-create-app.yaml

@@ -25,7 +25,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         task: [lint, typecheck, test]
@@ -50,7 +50,7 @@ jobs:
   ci-create-app-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, create-app-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-docs.yaml

@@ -27,7 +27,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 10
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0

.github/workflows/ci-emails.yaml

@@ -25,7 +25,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 10
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     steps:
       - name: Fetch custom Github Actions and base branch history
         uses: actions/checkout@v4
@@ -56,7 +56,7 @@ jobs:
   ci-emails-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, emails-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-front.yaml

@@ -14,8 +14,8 @@ concurrency:
 
 env:
   # restore-cache action adds 'v4-' prefix and '-<branch>-<sha>' suffix to the key
-  STORYBOOK_BUILD_CACHE_KEY_FOR_RESTORE_ACTION: storybook-build-depot-ubuntu-24.04-8-runner
-  STORYBOOK_BUILD_CACHE_KEY_FOR_SAVE_ACTION: v4-storybook-build-depot-ubuntu-24.04-8-runner-${{ github.ref_name }}-${{ github.sha }}
+  STORYBOOK_BUILD_CACHE_KEY_FOR_RESTORE_ACTION: storybook-build-ubuntu-latest-8-cores-runner
+  STORYBOOK_BUILD_CACHE_KEY_FOR_SAVE_ACTION: v4-storybook-build-ubuntu-latest-8-cores-runner-${{ github.ref_name }}-${{ github.sha }}
 
 jobs:
   changed-files-check:
@@ -42,7 +42,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     env:
       REACT_APP_SERVER_BASE_URL: http://localhost:3000
     steps:
@@ -68,7 +68,7 @@ jobs:
           key: ${{ env.STORYBOOK_BUILD_CACHE_KEY_FOR_SAVE_ACTION }}
   front-sb-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: front-sb-build
     strategy:
       fail-fast: false
@@ -115,7 +115,7 @@ jobs:
       #     path: packages/twenty-front/coverage/storybook/coverage-shard-${{matrix.shard}}.json
   # merge-reports-and-check-coverage:
   #   timeout-minutes: 30
-  #   runs-on: depot-ubuntu-24.04
+  #   runs-on: ubuntu-latest
   #   needs: front-sb-test
   #   env:
   #     PATH_TO_COVERAGE: packages/twenty-front/coverage/storybook
@@ -143,7 +143,7 @@ jobs:
     timeout-minutes: 30
     if: false
     needs: front-sb-build
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     env:
       REACT_APP_SERVER_BASE_URL: http://127.0.0.1:3000
       CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
@@ -169,7 +169,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     env:
       NODE_OPTIONS: '--max-old-space-size=4096'
       TASK_CACHE_KEY: front-task-${{ matrix.task }}
@@ -211,7 +211,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     env:
       NODE_OPTIONS: "--max-old-space-size=10240"
     steps:
@@ -236,7 +236,7 @@ jobs:
       #     path: packages/twenty-front/build
       #     retention-days: 1
   e2e-test:
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check-e2e, front-build]
     if: |
       always() &&
@@ -349,7 +349,7 @@ jobs:
   ci-front-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs:
       [
         changed-files-check,
@@ -366,7 +366,7 @@ jobs:
   ci-e2e-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check-e2e, e2e-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-release-create.yaml

@@ -25,7 +25,7 @@ defaults:
 jobs:
   create_pr:
     timeout-minutes: 10
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/ci-release-merge.yaml

@@ -15,7 +15,7 @@ defaults:
 jobs:
   tag_and_release:
     timeout-minutes: 10
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release')
     steps:
       - name: Check PR Author

.github/workflows/ci-sdk.yaml

@@ -23,7 +23,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         task: [lint, typecheck, test:unit, storybook:build, storybook:test, test:integration]
@@ -50,7 +50,7 @@ jobs:
           tasks: ${{ matrix.task }}
   sdk-e2e-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: [changed-files-check, sdk-test]
     if: needs.changed-files-check.outputs.any_changed == 'true'
     services:
@@ -94,7 +94,7 @@ jobs:
   ci-sdk-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, sdk-test, sdk-e2e-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-server.yaml

@@ -31,7 +31,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
@@ -143,7 +143,7 @@ jobs:
           key: ${{ steps.restore-server-setup-cache.outputs.cache-primary-key }}
   server-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: server-setup
     steps:
       - name: Fetch custom Github Actions and base branch history
@@ -164,7 +164,7 @@ jobs:
 
   server-integration-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: server-setup
     strategy:
       fail-fast: false
@@ -250,7 +250,7 @@ jobs:
   ci-server-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, server-setup, server-test, server-integration-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-shared.yaml

@@ -22,7 +22,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     env:
       NODE_OPTIONS: '--max-old-space-size=4096'
     strategy:
@@ -47,7 +47,7 @@ jobs:
   ci-shared-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, shared-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-test-docker-compose.yaml

@@ -23,7 +23,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -92,7 +92,7 @@ jobs:
   ci-test-docker-compose-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-utils.yaml

@@ -22,7 +22,7 @@ concurrency:
 jobs:
   danger-js:
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     if: github.event.action != 'closed'
     steps:
       - uses: actions/checkout@v4
@@ -35,7 +35,7 @@ jobs:
 
   congratulate:
     timeout-minutes: 3
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     if: github.event.action == 'closed' && github.event.pull_request.merged == true
     steps:
       - uses: actions/checkout@v4

.github/workflows/ci-website.yaml

@@ -23,7 +23,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 10
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
@@ -65,7 +65,7 @@ jobs:
   ci-website-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, website-build]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-zapier.yaml

@@ -28,7 +28,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
@@ -95,7 +95,7 @@ jobs:
     needs: server-setup
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         task: [lint, typecheck, validate]
@@ -120,7 +120,7 @@ jobs:
   ci-zapier-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     needs: [changed-files-check, zapier-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/claude.yml

@@ -23,7 +23,7 @@ jobs:
       (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && github.event.comment.user.type != 'Bot') ||
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && github.event.review.user.type != 'Bot') ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     timeout-minutes: 60
     permissions:
       contents: write
@@ -96,7 +96,7 @@ jobs:
 
   claude-cross-repo:
     if: github.event_name == 'repository_dispatch'
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     timeout-minutes: 60
     permissions:
       contents: write

.github/workflows/docs-i18n-pull.yaml

@@ -34,7 +34,7 @@ concurrency:
 jobs:
   pull_docs_translations:
     name: Pull docs translations
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/docs-i18n-push.yaml

@@ -21,7 +21,7 @@ concurrency:
 jobs:
   push_docs:
     name: Push documentation to Crowdin
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/i18n-pull.yaml

@@ -32,7 +32,7 @@ concurrency:
 jobs:
   pull_translations:
     name: Pull translations
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/i18n-push.yaml

@@ -17,7 +17,7 @@ concurrency:
 jobs:
   extract_translations:
     name: Extract and upload translations
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/preview-env-dispatch.yaml

@@ -33,7 +33,7 @@ jobs:
         )
       )
     timeout-minutes: 5
-    runs-on: depot-ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
       - name: Trigger preview environment workflow
         uses: peter-evans/repository-dispatch@v2

.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch

@@ -0,0 +1,58 @@
+diff --git a/esm/cache.js b/esm/cache.js
+index 07cf6d7dd99effb9c3464b620ba67a7f445224f5..248bb527923499a6be8065ee7a3613b55819c58c 100644
+--- a/esm/cache.js
++++ b/esm/cache.js
+@@ -69,17 +69,20 @@ export class TransformCacheCollection {
+       this.invalidate(cacheName, filename);
+     });
+   }
+-  invalidateIfChanged(filename, content) {
++  invalidateIfChanged(filename, content, _visited) {
++    const visited = _visited || new Set();
++    if (visited.has(filename)) {
++      return false;
++    }
++    visited.add(filename);
+     const fileEntrypoint = this.get('entrypoints', filename);
+ 
+-    // We need to check all dependencies of the file
+-    // because they might have changed as well.
+     if (fileEntrypoint) {
+       for (const [, dependency] of fileEntrypoint.dependencies) {
+         const dependencyFilename = dependency.resolved;
+         if (dependencyFilename) {
+           const dependencyContent = fs.readFileSync(dependencyFilename, 'utf8');
+-          this.invalidateIfChanged(dependencyFilename, dependencyContent);
++          this.invalidateIfChanged(dependencyFilename, dependencyContent, visited);
+         }
+       }
+     }
+diff --git a/lib/cache.js b/lib/cache.js
+index 0762ed7d3c39b31000f7aa7d8156da15403c8e64..6955410cd3c9ec53cf7a01c8346abc4c47fff791 100644
+--- a/lib/cache.js
++++ b/lib/cache.js
+@@ -77,17 +77,20 @@ class TransformCacheCollection {
+       this.invalidate(cacheName, filename);
+     });
+   }
+-  invalidateIfChanged(filename, content) {
++  invalidateIfChanged(filename, content, _visited) {
++    const visited = _visited || new Set();
++    if (visited.has(filename)) {
++      return false;
++    }
++    visited.add(filename);
+     const fileEntrypoint = this.get('entrypoints', filename);
+ 
+-    // We need to check all dependencies of the file
+-    // because they might have changed as well.
+     if (fileEntrypoint) {
+       for (const [, dependency] of fileEntrypoint.dependencies) {
+         const dependencyFilename = dependency.resolved;
+         if (dependencyFilename) {
+           const dependencyContent = _nodeFs.default.readFileSync(dependencyFilename, 'utf8');
+-          this.invalidateIfChanged(dependencyFilename, dependencyContent);
++          this.invalidateIfChanged(dependencyFilename, dependencyContent, visited);
+         }
+       }
+     }

CLAUDE.md

@@ -90,7 +90,7 @@ npx nx run twenty-front:graphql:generate --configuration=metadata
 ## Architecture Overview
 
 ### Tech Stack
-- **Frontend**: React 18, TypeScript, Jotai (state management), Emotion (styling), Vite
+- **Frontend**: React 18, TypeScript, Jotai (state management), Linaria (styling), Vite
 - **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)
 - **Monorepo**: Nx workspace managed with Yarn 4
 
@@ -175,7 +175,7 @@ IMPORTANT: Use Context7 for code generation, setup or configuration steps, or li
 5. Run `graphql:generate` after any GraphQL schema changes
 
 ### Code Style Notes
-- Use **Emotion** for styling with styled-components pattern
+- Use **Linaria** for styling with zero-runtime CSS-in-JS (styled-components pattern)
 - Follow **Nx** workspace conventions for imports
 - Use **Lingui** for internationalization
 - Apply security first, then formatting (sanitize before format)

README.md

@@ -109,7 +109,7 @@ Below are a few features we have implemented to date:
 - [TypeScript](https://www.typescriptlang.org/)
 - [Nx](https://nx.dev/)
 - [NestJS](https://nestjs.com/), with [BullMQ](https://bullmq.io/), [PostgreSQL](https://www.postgresql.org/), [Redis](https://redis.io/)
-- [React](https://reactjs.org/), with [Jotai](https://jotai.org/), [Emotion](https://emotion.sh/) and [Lingui](https://lingui.dev/)
+- [React](https://reactjs.org/), with [Jotai](https://jotai.org/), [Linaria](https://linaria.dev/) and [Lingui](https://lingui.dev/)
 
 
 

docs/emotion-to-linaria-migration-plan.md

@@ -1,381 +0,0 @@
-# Emotion → Linaria Migration Plan: twenty-front
-
-## Overview
-
-Migrate all Emotion (`@emotion/styled`, `@emotion/react`) usages in
-`packages/twenty-front/src` to Linaria (`@linaria/react`, `@linaria/core`),
-following the same patterns already established in the `twenty-ui` package.
-
-Linaria is a **zero-runtime** CSS-in-JS library. Styles are extracted at
-build time by [wyw-in-js](https://wyw-in-js.dev/) (the Vite plugin is
-`@wyw-in-js/vite`, already configured in `twenty-front/vite.config.ts`).
-This means every expression inside a `styled` or `css` template literal
-must be statically evaluable at build time — no runtime theme objects,
-no closures over component state, no side-effects.
-
-**Total files to migrate: ~998**
-
-| Category | Files | Description |
-|---|---|---|
-| styled-only | 694 | Import `@emotion/styled` but not `useTheme` |
-| styled + useTheme | 224 | Import both `@emotion/styled` and `useTheme` |
-| useTheme-only | 79 | Import `useTheme` but not `@emotion/styled` |
-| css / Global only | 1 | Import `css` or `Global` from `@emotion/react` only |
-
-## Theme Architecture
-
-Two build-time utilities produce the theme system:
-
-- **`buildThemeReferencingRootCssVariables`** — walks the theme object and
-  builds a nested mirror where every leaf is a `var(--t-xxx)` string
-  (evaluated at build time by wyw-in-js)
-- **`prepareThemeForRootCssVariableInjection`** — walks the runtime theme
-  and collects flat `[--css-variable-name, value]` pairs, injected onto
-  `document.documentElement` by `ThemeCssVariableInjectorEffect`
-
-`themeCssVariables` is the build-time object; every leaf resolves to a CSS
-`var()` reference. It is safe to use inside `styled` and `css` templates
-because wyw-in-js can evaluate it statically.
-
-## Migration Patterns
-
-### 1. `styled` import
-
-```diff
-- import styled from '@emotion/styled';
-+ import { styled } from '@linaria/react';
-```
-
-### 2. Theme access in styled components
-
-Replace Emotion's `({ theme }) =>` prop-function pattern with static
-`themeCssVariables` references:
-
-```diff
-+ import { themeCssVariables } from 'twenty-ui/theme';
-
-  const StyledTitle = styled.span`
--   color: ${({ theme }) => theme.font.color.primary};
--   font-size: ${({ theme }) => theme.font.size.lg};
-+   color: ${themeCssVariables.font.color.primary};
-+   font-size: ${themeCssVariables.font.size.lg};
-  `;
-```
-
-### 3. Spacing
-
-`theme.spacing(N)` is a function; in Linaria it becomes an indexed lookup:
-
-```diff
-- margin-top: ${({ theme }) => theme.spacing(3)};
-+ margin-top: ${themeCssVariables.spacing[3]};
-```
-
-For multi-arg spacing like `theme.spacing(2, 4)` → `"8px 16px"`:
-
-```diff
-- padding: ${({ theme }) => theme.spacing(2, 4)};
-+ padding: ${themeCssVariables.spacing[2]} ${themeCssVariables.spacing[4]};
-```
-
-The spacing scale covers integers 0–32 plus `0.5` and `1.5`. Any other
-fractional values (`0.25`, `0.75`, `1.25`, `2.5`, `3.5`) must be replaced
-with literal pixel values (e.g. `theme.spacing(2.5)` → `10px`).
-
-### 4. `useTheme` → `useContext(ThemeContext)`
-
-For runtime theme access (icon sizes, animation durations, conditional logic
-outside of styled components):
-
-```diff
-- import { useTheme } from '@emotion/react';
-+ import { useContext } from 'react';
-+ import { ThemeContext } from 'twenty-ui/theme';
-
-  const MyComponent = () => {
--   const theme = useTheme();
-+   const { theme } = useContext(ThemeContext);
-    return <Icon size={theme.icon.size.sm} />;
-  };
-```
-
-### 5. `css` template literal
-
-Linaria's `css` (from `@linaria/core`) returns a **class name string**, not
-a serialized style object like Emotion's `css`. This has two consequences:
-
-**Standalone usage** — apply via `className`, not the `css` prop:
-
-```diff
-- import { css } from '@emotion/react';
-+ import { css } from '@linaria/core';
-
-  const myClass = css`
-    text-decoration: none;
-  `;
-
-- <Link css={myClass} />
-+ <Link className={myClass} />
-```
-
-**Inside `styled` templates** — do NOT nest `css` tags. Linaria's `css`
-returns a class name, not raw CSS text, so interpolating it inside `styled`
-produces broken output. Use plain strings instead:
-
-```diff
-  // WRONG — css`` returns a class name, not CSS text
-  ${({ handle }) =>
-    handle === 'left'
--     ? css`left: ${themeCssVariables.spacing[1]};`
--     : css`right: ${themeCssVariables.spacing[1]};`}
-+     ? `left: ${themeCssVariables.spacing[1]};`
-+     : `right: ${themeCssVariables.spacing[1]};`}
-```
-
-### 6. Interpolation return types
-
-wyw-in-js requires prop interpolation functions to return `string | number`.
-They must **never** return `false`, `undefined`, or `null`. Replace
-short-circuit `&&` with ternary expressions:
-
-```diff
-  // WRONG — returns false when condition is false
-- ${({ isActive }) => isActive && `background: ${themeCssVariables.color.blue};`}
-  // CORRECT
-+ ${({ isActive }) => isActive ? `background: ${themeCssVariables.color.blue};` : ''}
-```
-
-### 7. Block interpolations (multi-declaration returns)
-
-Linaria wraps each interpolation result in a single CSS custom property
-(`var(--xxx)`). An interpolation that returns **multiple CSS declarations**
-produces invalid CSS. Split into one interpolation per property:
-
-```diff
-  // WRONG — single interpolation returning multiple declarations
-- ${({ divider, theme }) => {
--   const border = `1px solid ${theme.border.color.light}`;
--   return divider === 'left' ? `border-left: ${border}` : `border-right: ${border}`;
-- }}
-
-  // CORRECT — one interpolation per property
-+ border-left: ${({ divider }) =>
-+   divider === 'left' ? `1px solid ${themeCssVariables.border.color.light}` : 'none'};
-+ border-right: ${({ divider }) =>
-+   divider === 'right' ? `1px solid ${themeCssVariables.border.color.light}` : 'none'};
-```
-
-### 8. CSS var + unit concatenation
-
-CSS custom properties can't be concatenated with unit suffixes directly
-(`var(--x)px` is invalid). Use `calc()` to attach units:
-
-```diff
-- transition: background ${themeCssVariables.animation.duration.instant}s ease;
-+ transition: background calc(${themeCssVariables.animation.duration.instant} * 1s) ease;
-```
-
-### 9. `styled(Component)` requires `className`
-
-Linaria's `styled(Component)` works by passing a generated `className` to
-the wrapped component. The component **must** accept and forward a
-`className` prop — otherwise the styles are silently lost. If the component
-doesn't support it, either add `className` support or use a wrapper div.
-
-Linaria also does **not** support Emotion's `shouldForwardProp` option.
-Custom props on HTML elements are automatically filtered by Linaria's
-runtime (via `@emotion/is-prop-valid`). For custom components, all props are
-forwarded — ensure the wrapped component ignores unknown props gracefully.
-
-### 10. `type Theme` → `type ThemeType`
-
-```diff
-- import { type Theme } from '@emotion/react';
-+ import { type ThemeType } from 'twenty-ui/theme';
-```
-
-### 11. Framer Motion integration
-
-Linaria doesn't support `styled(motion.div)` — wrapping a motion element
-with `styled()` causes the component body to be stripped at build time by
-wyw-in-js. Define the styled component first, then wrap with
-`motion.create()`:
-
-```tsx
-const StyledBarBase = styled.div`
-  background-color: ${themeCssVariables.font.color.primary};
-  height: 100%;
-`;
-
-const StyledBar = motion.create(StyledBarBase);
-```
-
-### 12. Dynamic styles via CSS variables
-
-When a component needs to compute styles from multiple props with complex
-branching logic (e.g. combining `variant`, `accent`, `disabled`, `focus`),
-Linaria's prop interpolations become unwieldy. Use a `computeDynamicStyles`
-helper that returns a `CSSProperties` object injected via `style={}`,
-referenced from the static CSS with `var()`:
-
-```tsx
-const StyledButton = styled.button`
-  background: var(--btn-bg);
-  border-color: var(--btn-border-color);
-  &:hover { background: var(--btn-hover-bg); }
-`;
-
-const dynamicStyles = useMemo(() => {
-  const s = computeButtonDynamicStyles(variant, accent, ...);
-  return {
-    '--btn-bg': s.background,
-    '--btn-hover-bg': s.hoverBackground,
-  } as CSSProperties;
-}, [variant, accent, ...]);
-
-return <StyledButton style={dynamicStyles} />;
-```
-
-### 13. `Global` component
-
-Replace Emotion's `<Global styles={...} />` with standard CSS or the
-`ThemeCssVariableInjectorEffect` pattern from twenty-ui.
-
-### 14. `ThemeProvider`
-
-The `BaseThemeProvider` already wraps children with both Emotion's
-`ThemeProvider` and Linaria's `ThemeContextProvider`. Once all Emotion usages
-are gone, the Emotion `ThemeProvider` wrapper can be removed.
-
----
-
-## PR Breakdown
-
-Files are grouped to keep each PR around ~100 files with consistent review
-surface. We start with the simplest, lowest-risk modules.
-
-### PR 1 (~97 files) — Small standalone modules
-
-Low-risk modules with mostly simple `styled`-only patterns.
-
-| Module | Files |
-|---|---|
-| spreadsheet-import | 28 |
-| billing | 10 |
-| views | 14 |
-| navigation-menu-item | 14 |
-| blocknote-editor | 7 |
-| advanced-text-editor | 7 |
-| favorites | 7 |
-| navigation | 4 |
-| information-banner | 3 |
-| sign-in-background-mock | 3 |
-
-### PR 2 (~100 files) — Auth, tiny modules, loading, testing, pages (part 1)
-
-| Module | Files |
-|---|---|
-| auth | 19 |
-| action-menu | 3 |
-| object-metadata | 3 |
-| onboarding | 2 |
-| workspace | 2 |
-| file | 2 |
-| error-handler | 2 |
-| front-components | 1 |
-| geo-map | 1 |
-| hooks | 1 |
-| loading | 5 |
-| testing | 5 |
-| pages (first ~55 files) | ~55 |
-
-### PR 3 (~97 files) — Pages (remaining) + activities + AI
-
-| Module | Files |
-|---|---|
-| pages (remaining ~16 files) | ~16 |
-| activities | 53 |
-| ai | 28 |
-
-### PR 4 (~100 files) — Command-menu + workflow (part 1)
-
-| Module | Files |
-|---|---|
-| command-menu | 53 |
-| workflow (first ~47 files) | ~47 |
-
-### PR 5 (~115 files) — Workflow (remaining) + page-layout
-
-| Module | Files |
-|---|---|
-| workflow (remaining ~32 files) | ~32 |
-| page-layout | 83 |
-
-### PR 6 (~100 files) — UI module (part 1)
-
-| Module | Files |
-|---|---|
-| ui (first ~100 files) | ~100 |
-
-### PR 7 (~85 files) — UI module (remaining) + object-record (start)
-
-| Module | Files |
-|---|---|
-| ui (remaining ~23 files) | ~23 |
-| object-record (first ~62 files) | ~62 |
-
-### PR 8 (~100 files) — Object-record (continued)
-
-| Module | Files |
-|---|---|
-| object-record (next ~100 files) | ~100 |
-
-### PR 9 (~100 files) — Settings (part 1)
-
-| Module | Files |
-|---|---|
-| settings (first ~100 files) | ~100 |
-
-### PR 10 (~102 files) — Settings (part 2) + final cleanup
-
-| Module | Files |
-|---|---|
-| settings (remaining ~102 files) | ~102 |
-| css/Global-only file | 1 |
-
-### Post-migration PR — Remove Emotion
-
-Once all PRs are merged:
-
-- Remove `ThemeProvider` from `@emotion/react` in `BaseThemeProvider`
-- Remove `@emotion/styled` and `@emotion/react` dependencies
-- Remove `@styled/typescript-styled-plugin` from tsconfig
-- Clean up any remaining Emotion-related configuration
-
----
-
-## Risk Assessment
-
-| Risk | Mitigation |
-|---|---|
-| wyw-in-js evaluates at build time; dynamic expressions may fail | Use `themeCssVariables` for static theme values; pass dynamic values as component props or via `style={}` CSS variables |
-| `theme.spacing(N)` function → `themeCssVariables.spacing[N]` index | Pre-computed for integers 0–32 plus 0.5 and 1.5; other fractional values → literal pixel values |
-| `useTheme` used for runtime logic (not just styles) | Replace with `useContext(ThemeContext)`, destructure `{ theme }` |
-| Multi-arg `theme.spacing(a, b, c)` | Split into individual `themeCssVariables.spacing[N]` references |
-| `css` tag inside `styled` templates | Linaria `css` returns class name, not CSS text; use plain strings inside `styled` |
-| Interpolation returns `false` / `undefined` | wyw-in-js requires `string \| number`; use ternary `? : ''` instead of `&&` |
-| Block interpolations (multiple declarations) | Split into one interpolation per CSS property |
-| `var(--x)px` concatenation | Use `calc(var(--x) * 1px)` |
-| `styled(motion.div)` stripped by wyw-in-js | Use `motion.create(StyledBase)` pattern |
-| `styled(Component)` with no `className` prop | Add `className` support to wrapped component or use wrapper div |
-| Complex multi-prop style branching | Use `computeDynamicStyles` + `style={}` + `var()` references |
-
----
-
-## Validation Checklist (per PR)
-
-- [ ] `npx nx lint:diff-with-main twenty-front` passes
-- [ ] `npx nx typecheck twenty-front` passes
-- [ ] `npx nx test twenty-front` passes
-- [ ] Visual spot-check of affected components in the app
-- [ ] No remaining `@emotion/styled` or `@emotion/react` imports in migrated files

npm-app-distribution-plan.md

@@ -1,283 +0,0 @@
-# npm-Based App Distribution for Twenty
-
-*Technical Design Document -- February 2026*
-
-## Overview
-
-Add npm registry support for distributing Twenty apps (public and private), with per-AppRegistration registry overrides, direct tarball upload as escape hatch, and version upgrade detection.
-
-## Assumptions
-
-- The marketplace install flow (currently a TODO in the resolver and frontend) will be implemented separately. This plan provides the infrastructure that install flow will call into.
-- The existing `app:dev` flow (individual file uploads via CLI) remains unchanged.
-- The existing GitHub-based marketplace discovery remains as a curated fallback.
-
-## Architecture
-
-```
-                    Developer
-                   /    |     \
-          npm publish   |   twenty app:push
-             /          |          \
-      npmjs.com    Private Reg   Server REST Upload
-         |              |              |
-         v              v              v
-    [Discovery Layer]           [Direct Upload]
-     npm search API                    |
-     GitHub curated list               |
-         |                             |
-         v                             |
-    MarketplaceService                 |
-     (sourcePackage in DTO)            |
-         |                             |
-         v                             v
-    AppPackageResolverService  <--------+
-     .npmrc generation
-     yarn add / tarball extract
-              |
-              v
-    ApplicationSyncService (existing)
-     WorkspaceMigrationRunnerService
-              |
-              v
-    AppRegistration + Application entities
-```
-
-## Phase 1: Entity and Config Changes
-
-### 1a. Extend AppRegistrationEntity
-
-Add four columns to `application-registration.entity.ts`:
-
-- **`sourcePackage`** (text, nullable) -- npm package name, e.g. `"twenty-app-fireflies"` or `"@myorg/twenty-app-crm"`. Null for tarball-only or OAuth-only apps.
-- **`tarballFileId`** (uuid, nullable) -- FK to a FileEntity storing a directly-uploaded `.tar.gz`. Null when the app comes from npm.
-- **`registryUrl`** (text, nullable) -- per-registration npm registry override. Null means "use the server default `APP_REGISTRY_URL`." This is how a single server can pull public apps from npmjs.com while pulling `@mycompany/*` apps from GitHub Packages.
-- **`latestAvailableVersion`** (text, nullable) -- cached latest version from the registry, updated periodically. Compared against `Application.version` to surface upgrade availability.
-
-**Source resolution priority:**
-
-1. `sourcePackage` is set → resolve from npm via `yarn add`
-2. `tarballFileId` is set → extract from file storage
-3. Neither → OAuth-only app, no server-side code
-
-### 1b. Extend ApplicationEntity.sourceType
-
-Widen the `sourceType` union from `'local'` to `'local' | 'npm' | 'tarball'`:
-
-- `'local'` -- existing behavior (CLI `app:dev`, individual file uploads, workspace-custom)
-- `'npm'` -- installed from an npm registry via `yarn add`
-- `'tarball'` -- installed from a directly-uploaded tarball
-
-This lets the system distinguish how an app was installed, which matters for upgrade logic (npm apps can check the registry for newer versions; tarball apps cannot).
-
-### 1c. Add server-wide config variables
-
-Add a new `APP_REGISTRY_CONFIG` group to ConfigVariablesGroup:
-
-- **`APP_REGISTRY_URL`** (string, default `https://registry.npmjs.org`) -- default npm registry URL
-- **`APP_REGISTRY_TOKEN`** (string, optional, sensitive) -- auth token for the default registry
-
-### 1d. Generate migration
-
-TypeORM migration adding `sourcePackage`, `tarballFileId`, `registryUrl`, `latestAvailableVersion` to `core.applicationRegistration`.
-
-## Phase 2: App Package Resolver Service
-
-### 2a. Create AppPackageResolverService
-
-New service with core method:
-
-```
-resolvePackage(appRegistration, options?: { targetVersion? }) → ResolvedPackage | null
-```
-
-Returns `{ manifestPath, packageJsonPath, filesDir }` or null for OAuth-only apps.
-
-**Resolution logic:**
-
-```
-if sourcePackage:
-  1. Determine registry: appRegistration.registryUrl ?? APP_REGISTRY_URL
-  2. Determine auth token for the resolved registry
-  3. Generate temporary .npmrc in an isolated working directory
-  4. Run: yarn add <sourcePackage>@<targetVersion ?? latest>
-  5. Read manifest from node_modules/<sourcePackage>/.twenty/output/manifest.json
-  6. Return paths
-
-if tarballFileId:
-  1. Download tarball from FileStorageService
-  2. Extract to temporary directory
-  3. Read manifest from extracted files
-  4. Return paths
-
-else:
-  return null (OAuth-only)
-```
-
-### 2b. Isolated working directories
-
-Each resolution runs in a temporary directory under `{os.tmpdir()}/twenty-app-resolver/{uuid}/`. This avoids contaminating the server's own `node_modules` and isolates apps from each other. Cleaned up after files are copied to storage.
-
-### 2c. .npmrc generation
-
-For scoped packages (`@scope/twenty-app-*`):
-
-```
-@scope:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=TOKEN
-```
-
-For unscoped packages with a non-default registry:
-
-```
-registry=https://my-verdaccio.internal:4873
-//my-verdaccio.internal:4873/:_authToken=TOKEN
-```
-
-### 2d. Post-resolution file transfer
-
-After resolving, copies files into the app's storage path using the existing FileStorageService layout:
-
-```
-{workspaceId}/{applicationUniversalIdentifier}/
-  built-logic-function/...
-  built-front-component/...
-  dependencies/package.json
-  dependencies/yarn.lock
-  public-asset/...
-  source/...
-```
-
-This reuses the same FileFolder enum paths that `app:dev` uses, so downstream ApplicationSyncService works unchanged.
-
-## Phase 3: Marketplace Discovery via npm
-
-### 3a. Update MarketplaceService
-
-Add npm-based discovery alongside the existing GitHub path:
-
-- Query npm search API: `GET {registryUrl}/-/v1/search?text=keywords:twenty-app&size=250`
-- Map each result to MarketplaceAppDTO using package.json metadata
-
-**Merge strategy:**
-
-1. Fetch from npm search API (apps with `keywords: ["twenty-app"]`)
-2. Fetch from GitHub (existing curated list)
-3. Merge by `universalIdentifier` -- GitHub entries override npm entries (allowing curation)
-4. Cache merged result with existing 1-hour TTL
-
-### 3b. Add sourcePackage to MarketplaceAppDTO
-
-The DTO needs a `sourcePackage: string | null` field so the install flow knows which npm package to resolve. For npm-discovered apps, this is the package name. For GitHub-only apps, this is null.
-
-## Phase 4: Version Upgrade Support
-
-### 4a. Create AppUpgradeService
-
-**Periodic version check (npm-sourced apps only):**
-
-- Fetches `{registryUrl}/{sourcePackage}/latest` from the npm registry
-- Stores result in `AppRegistration.latestAvailableVersion`
-- Frontend compares against `Application.version` to show "Update available"
-
-**Upgrade trigger:**
-
-1. Resolve the new version via AppPackageResolverService
-2. Sync via existing ApplicationSyncService (triggers workspace migration for schema changes)
-3. Update Application.version
-
-**Rollback strategy:** If sync fails (e.g., migration validation error), re-resolve the previous version and re-sync. This is possible because npm retains all published versions.
-
-### 4b. Version check scheduling
-
-Lightweight cron or check-on-access pattern. Iterates over AppRegistrations where `sourcePackage IS NOT NULL` and calls `checkForUpdates()`. Frequency: once per hour, matching the existing marketplace cache TTL.
-
-## Phase 5: SDK CLI Commands
-
-### 5a. Finalize `twenty app:build`
-
-Ensure `.twenty/output/` is npm-publishable. The build step generates a `package.json` in the output directory:
-
-```json
-{
-  "name": "twenty-app-fireflies",
-  "version": "1.2.0",
-  "keywords": ["twenty-app"],
-  "twenty": {
-    "universalIdentifier": "a4df0c0f-c65e-44e5-8436-24814182d4ac"
-  },
-  "files": ["manifest.json", "built-logic-function", "built-front-component", "public-asset"]
-}
-```
-
-The developer then publishes with standard `npm publish` -- no custom command needed.
-
-### 5b. `twenty app:pack` (new command)
-
-```
-twenty app:pack [appPath]
-```
-
-- Runs `app:build` if `.twenty/output/` doesn't exist or is stale
-- Uses existing TarballService to create `{name}-{version}.tar.gz`
-- Outputs the file path for manual distribution
-
-### 5c. `twenty app:push` (new command)
-
-```
-twenty app:push [appPath] --server <url> --token <token>
-```
-
-- Runs `app:pack` to produce the tarball
-- Reads universalIdentifier from manifest to find or create the AppRegistration
-- Uploads via `POST /api/app-registrations/upload-tarball`
-- Reports success with the registration ID
-- Reuses `twenty auth:login` credentials if `--server` is not specified
-
-## Phase 6: Server Tarball Upload Endpoint
-
-### 6a. REST controller
-
-```
-POST /api/app-registrations/upload-tarball
-Content-Type: multipart/form-data
-Body: tarball file + optional universalIdentifier
-```
-
-**Validation:**
-
-- Max file size: 50MB
-- Must be a valid `.tar.gz`
-- Extracted contents must contain `manifest.json` with a valid `universalIdentifier`
-- The `universalIdentifier` must not conflict with an existing registration owned by a different user
-
-**Flow:**
-
-1. Extract tarball to temp directory
-2. Validate manifest structure
-3. Find or create AppRegistration by universalIdentifier
-4. Store tarball in FileStorageService under `FileFolder.AppTarball`
-5. Set `tarballFileId` on the AppRegistration
-6. Return the AppRegistration entity
-
-### 6b. Add FileFolder.AppTarball
-
-New enum value `AppTarball = 'app-tarball'` in FileFolder.
-
-## Key Design Decisions
-
-| Decision | Rationale |
-|---|---|
-| Per-AppRegistration registry override | `registryUrl` on the entity allows mixing registries. Public apps from npmjs.com, private from GitHub Packages/Verdaccio. Server-wide `APP_REGISTRY_URL` is the fallback. |
-| npm publish is standard | No custom publish infra. Free versioning, README, `npm audit`, download stats, proven auth model. |
-| Tarball as escape hatch | Air-gapped environments, CI pipelines, one-off installs. Cannot auto-upgrade. |
-| sourceType distinction | `'npm' \| 'tarball' \| 'local'` lets the system know which upgrade path is available. Only npm apps can check for newer versions. |
-| Backward compatible | `app:dev` flow unchanged. GitHub marketplace unchanged. All new fields nullable. |
-| Upgrade rollback | Re-resolve previous version from npm on failure. Safe because npm never deletes published versions. |
-
-## Edge Cases
-
-- **npm unreachable**: Timeout after 30s, throw clear error. App remains at current installed version.
-- **Package name conflicts**: The `universalIdentifier` in the `twenty` field of `package.json` is the source of truth, not the npm package name. Two packages with the same universalIdentifier conflict at the AppRegistration level (unique index).
-- **Scoped vs unscoped packages**: Both work. Scoped packages naturally route to a private registry via `.npmrc` scope mapping.
-- **Multiple workspaces, same server**: AppRegistration is server-level (core schema). Application is workspace-level. One AppRegistration can be installed in multiple workspaces at different versions.

nx.json

@@ -276,7 +276,7 @@
   "generators": {
     "@nx/react": {
       "application": {
-        "style": "@emotion/styled",
+        "style": "@linaria/react",
         "linter": "eslint",
         "bundler": "vite",
         "compiler": "swc",
@@ -284,7 +284,7 @@
         "projectNameAndRootFormat": "derived"
       },
       "library": {
-        "style": "@emotion/styled",
+        "style": "@linaria/react",
         "linter": "eslint",
         "bundler": "vite",
         "compiler": "swc",
@@ -292,7 +292,7 @@
         "projectNameAndRootFormat": "derived"
       },
       "component": {
-        "style": "@emotion/styled"
+        "style": "@linaria/react"
       }
     }
   },

package.json

@@ -2,14 +2,13 @@
   "private": true,
   "dependencies": {
     "@apollo/client": "^3.7.17",
-    "@emotion/react": "^11.11.1",
-    "@emotion/styled": "^11.11.0",
     "@floating-ui/react": "^0.24.3",
     "@linaria/core": "^6.2.0",
     "@linaria/react": "^6.2.1",
     "@radix-ui/colors": "^3.0.0",
     "@sniptt/guards": "^0.2.0",
     "@tabler/icons-react": "^3.31.0",
+    "@wyw-in-js/babel-preset": "^1.0.6",
     "@wyw-in-js/vite": "^0.7.0",
     "archiver": "^7.0.1",
     "danger-plugin-todos": "^1.3.1",
@@ -41,12 +40,13 @@
     "lodash.snakecase": "^4.1.1",
     "lodash.upperfirst": "^4.3.1",
     "microdiff": "^1.3.2",
+    "next-with-linaria": "^1.3.0",
     "planer": "^1.2.0",
     "pluralize": "^8.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-responsive": "^9.0.2",
-    "react-router-dom": "^6.4.4",
+    "react-router-dom": "^6.30.3",
     "react-tooltip": "^5.13.1",
     "remark-gfm": "^4.0.1",
     "rxjs": "^7.2.0",
@@ -72,14 +72,14 @@
     "@graphql-codegen/typescript": "^3.0.4",
     "@graphql-codegen/typescript-operations": "^3.0.4",
     "@graphql-codegen/typescript-react-apollo": "^3.3.7",
-    "@nx/eslint": "22.3.3",
-    "@nx/eslint-plugin": "22.3.3",
-    "@nx/jest": "22.3.3",
-    "@nx/js": "22.3.3",
-    "@nx/react": "22.3.3",
-    "@nx/storybook": "22.3.3",
-    "@nx/vite": "22.3.3",
-    "@nx/web": "22.3.3",
+    "@nx/eslint": "22.5.4",
+    "@nx/eslint-plugin": "22.5.4",
+    "@nx/jest": "22.5.4",
+    "@nx/js": "22.5.4",
+    "@nx/react": "22.5.4",
+    "@nx/storybook": "22.5.4",
+    "@nx/vite": "22.5.4",
+    "@nx/web": "22.5.4",
     "@sentry/types": "^8",
     "@storybook-community/storybook-addon-cookie": "^5.0.0",
     "@storybook/addon-coverage": "^3.0.0",
@@ -90,10 +90,10 @@
     "@storybook/react-vite": "^10.2.13",
     "@storybook/test-runner": "^0.24.2",
     "@stylistic/eslint-plugin": "^1.5.0",
-    "@swc-node/register": "1.11.1",
-    "@swc/cli": "^0.3.12",
-    "@swc/core": "1.15.11",
-    "@swc/helpers": "~0.5.18",
+    "@swc-node/register": "^1.11.1",
+    "@swc/cli": "^0.7.10",
+    "@swc/core": "^1.15.11",
+    "@swc/helpers": "~0.5.19",
     "@swc/jest": "^0.2.39",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -170,7 +170,7 @@
     "jsdom": "~22.1.0",
     "msw": "^2.12.7",
     "msw-storybook-addon": "^2.0.6",
-    "nx": "22.3.3",
+    "nx": "22.5.4",
     "prettier": "^3.1.1",
     "raw-loader": "^4.0.2",
     "rimraf": "^5.0.5",
@@ -202,7 +202,9 @@
     "typescript": "5.9.2",
     "graphql-redis-subscriptions/ioredis": "^5.6.0",
     "@lingui/core": "5.1.2",
-    "@types/qs": "6.9.16"
+    "@types/qs": "6.9.16",
+    "@wyw-in-js/transform@npm:0.6.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch",
+    "@wyw-in-js/transform@npm:0.7.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch"
   },
   "version": "0.2.1",
   "nx": {},

packages/create-twenty-app/README.md

@@ -89,6 +89,7 @@ In interactive mode, you can pick from:
 - **Example view** — a saved view for the example object (`views/example-view.ts`)
 - **Example navigation menu item** — a sidebar link (`navigation-menu-items/example-navigation-menu-item.ts`)
 - **Example skill** — an AI agent skill definition (`skills/example-skill.ts`)
+- **Integration test** — a vitest integration test verifying app installation (`__tests__/app-install.integration-test.ts`)
 
 ## What gets scaffolded
 
@@ -108,6 +109,7 @@ In interactive mode, you can pick from:
 - `views/example-view.ts` — Example saved view for the example object
 - `navigation-menu-items/example-navigation-menu-item.ts` — Example sidebar navigation link
 - `skills/example-skill.ts` — Example AI agent skill definition
+- `__tests__/app-install.integration-test.ts` — Integration test that builds, installs, and verifies the app (includes `vitest.config.ts`, `tsconfig.spec.json`, and a setup file)
 
 ## Next steps
 - Run `yarn twenty help` to see all available commands.

packages/create-twenty-app/src/constants/base-application/README.md

@@ -36,6 +36,17 @@ yarn twenty function:execute  # Execute a function with JSON payload
 yarn twenty app:uninstall  # Uninstall app from workspace
 ```
 
+## Integration Tests
+
+If your project includes the example integration test (`src/__tests__/app-install.integration-test.ts`), you can run it with:
+
+```bash
+# Make sure a Twenty server is running at http://localhost:3000
+yarn test
+```
+
+The test builds and installs the app, then verifies it appears in the applications list. Test configuration (API URL and API key) is defined in `vitest.config.ts`.
+
 ## LLMs instructions
 
 Main docs and pitfalls are available in LLMS.md file.

packages/create-twenty-app/src/constants/base-application/tsconfig.json

@@ -27,5 +27,5 @@
       "~/*": ["./*"]
     }
   },
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts", "**/*.integration-test.ts"]
 }

packages/create-twenty-app/src/create-app.command.ts

@@ -115,6 +115,7 @@ export class CreateAppCommand {
         includeExampleView: false,
         includeExampleNavigationMenuItem: false,
         includeExampleSkill: false,
+        includeExampleIntegrationTest: false,
       };
     }
 
@@ -127,6 +128,7 @@ export class CreateAppCommand {
         includeExampleView: true,
         includeExampleNavigationMenuItem: true,
         includeExampleSkill: true,
+        includeExampleIntegrationTest: true,
       };
     }
 
@@ -171,12 +173,19 @@ export class CreateAppCommand {
             value: 'skill',
             checked: true,
           },
+          {
+            name: 'Integration test (vitest test verifying app installation)',
+            value: 'integrationTest',
+            checked: true,
+          },
         ],
       },
     ]);
 
     const includeField = selectedExamples.includes('field');
     const includeView = selectedExamples.includes('view');
+    const includeExampleIntegrationTest =
+      selectedExamples.includes('integrationTest');
     const includeObject =
       selectedExamples.includes('object') || includeField || includeView;
 
@@ -197,6 +206,7 @@ export class CreateAppCommand {
       includeExampleNavigationMenuItem:
         selectedExamples.includes('navigationMenuItem'),
       includeExampleSkill: selectedExamples.includes('skill'),
+      includeExampleIntegrationTest,
     };
   }
 

packages/create-twenty-app/src/types/scaffolding-options.ts

@@ -8,4 +8,5 @@ export type ExampleOptions = {
   includeExampleView: boolean;
   includeExampleNavigationMenuItem: boolean;
   includeExampleSkill: boolean;
+  includeExampleIntegrationTest: boolean;
 };

packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts

@@ -1,10 +1,10 @@
 import { type ExampleOptions } from '@/types/scaffolding-options';
-import { GENERATED_DIR } from 'twenty-shared/application';
 import { copyBaseApplicationProject } from '@/utils/app-template';
 import * as fs from 'fs-extra';
 import { tmpdir } from 'os';
-import { join } from 'path';
 import createTwentyAppPackageJson from 'package.json';
+import { join } from 'path';
+import { GENERATED_DIR } from 'twenty-shared/application';
 
 jest.mock('fs-extra', () => {
   const actual = jest.requireActual('fs-extra');
@@ -25,6 +25,16 @@ const ALL_EXAMPLES: ExampleOptions = {
   includeExampleView: true,
   includeExampleNavigationMenuItem: true,
   includeExampleSkill: true,
+  includeExampleIntegrationTest: true,
+};
+
+const SEED_TSCONFIG = {
+  compilerOptions: { paths: { 'src/*': ['./src/*'] } },
+  exclude: ['node_modules', 'dist', '**/*.integration-test.ts'],
+};
+
+const seedTsconfig = async (directory: string) => {
+  await fs.writeJson(join(directory, 'tsconfig.json'), SEED_TSCONFIG);
 };
 
 const NO_EXAMPLES: ExampleOptions = {
@@ -35,6 +45,7 @@ const NO_EXAMPLES: ExampleOptions = {
   includeExampleFrontComponent: false,
   includeExampleView: false,
   includeExampleNavigationMenuItem: false,
+  includeExampleIntegrationTest: false,
 };
 
 describe('copyBaseApplicationProject', () => {
@@ -46,6 +57,7 @@ describe('copyBaseApplicationProject', () => {
       `test-twenty-app-${Date.now()}-${Math.random().toString(36).slice(2)}`,
     );
     await fs.ensureDir(testAppDirectory);
+    await seedTsconfig(testAppDirectory);
     jest.clearAllMocks();
   });
 
@@ -149,11 +161,18 @@ describe('copyBaseApplicationProject', () => {
       "import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'",
     );
 
+    expect(appConfigContent).toContain(
+      'export const APPLICATION_UNIVERSAL_IDENTIFIER',
+    );
+    expect(appConfigContent).toContain(
+      'universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER',
+    );
+
     expect(appConfigContent).toContain("displayName: 'My Test App'");
     expect(appConfigContent).toContain("description: 'A test application'");
 
     expect(appConfigContent).toMatch(
-      /universalIdentifier: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
+      /APPLICATION_UNIVERSAL_IDENTIFIER =\s*'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
     );
 
     expect(appConfigContent).toContain(
@@ -235,6 +254,7 @@ describe('copyBaseApplicationProject', () => {
   it('should generate unique UUIDs for each application', async () => {
     const firstAppDir = join(testAppDirectory, 'app1');
     await fs.ensureDir(firstAppDir);
+    await seedTsconfig(firstAppDir);
     await copyBaseApplicationProject({
       appName: 'app-one',
       appDisplayName: 'App One',
@@ -245,6 +265,7 @@ describe('copyBaseApplicationProject', () => {
 
     const secondAppDir = join(testAppDirectory, 'app2');
     await fs.ensureDir(secondAppDir);
+    await seedTsconfig(secondAppDir);
     await copyBaseApplicationProject({
       appName: 'app-two',
       appDisplayName: 'App Two',
@@ -263,7 +284,7 @@ describe('copyBaseApplicationProject', () => {
     );
 
     const uuidRegex =
-      /universalIdentifier: '([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
+      /APPLICATION_UNIVERSAL_IDENTIFIER =\s*'([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
     const firstUuid = firstAppConfig.match(uuidRegex)?.[1];
     const secondUuid = secondAppConfig.match(uuidRegex)?.[1];
 
@@ -275,6 +296,7 @@ describe('copyBaseApplicationProject', () => {
   it('should generate unique role UUIDs for each application', async () => {
     const firstAppDir = join(testAppDirectory, 'app1');
     await fs.ensureDir(firstAppDir);
+    await seedTsconfig(firstAppDir);
     await copyBaseApplicationProject({
       appName: 'app-one',
       appDisplayName: 'App One',
@@ -285,6 +307,7 @@ describe('copyBaseApplicationProject', () => {
 
     const secondAppDir = join(testAppDirectory, 'app2');
     await fs.ensureDir(secondAppDir);
+    await seedTsconfig(secondAppDir);
     await copyBaseApplicationProject({
       appName: 'app-two',
       appDisplayName: 'App Two',
@@ -355,6 +378,12 @@ describe('copyBaseApplicationProject', () => {
           ),
         ).toBe(true);
 
+        expect(
+          await fs.pathExists(
+            join(srcPath, '__tests__', 'app-install.integration-test.ts'),
+          ),
+        ).toBe(true);
+
         // Install functions should always exist
         expect(
           await fs.pathExists(
@@ -428,6 +457,11 @@ describe('copyBaseApplicationProject', () => {
             ),
           ),
         ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, '__tests__', 'app-install.integration-test.ts'),
+          ),
+        ).toBe(false);
       });
     });
 
@@ -446,6 +480,7 @@ describe('copyBaseApplicationProject', () => {
             includeExampleFrontComponent: true,
             includeExampleView: false,
             includeExampleNavigationMenuItem: false,
+            includeExampleIntegrationTest: false,
           },
         });
 
@@ -483,6 +518,7 @@ describe('copyBaseApplicationProject', () => {
             includeExampleFrontComponent: false,
             includeExampleView: false,
             includeExampleNavigationMenuItem: false,
+            includeExampleIntegrationTest: false,
           },
         });
 
@@ -540,6 +576,7 @@ describe('copyBaseApplicationProject', () => {
     it('should generate unique UUIDs for example objects across apps', async () => {
       const firstAppDir = join(testAppDirectory, 'app1');
       await fs.ensureDir(firstAppDir);
+      await seedTsconfig(firstAppDir);
       await copyBaseApplicationProject({
         appName: 'app-one',
         appDisplayName: 'App One',
@@ -550,6 +587,7 @@ describe('copyBaseApplicationProject', () => {
 
       const secondAppDir = join(testAppDirectory, 'app2');
       await fs.ensureDir(secondAppDir);
+      await seedTsconfig(secondAppDir);
       await copyBaseApplicationProject({
         appName: 'app-two',
         appDisplayName: 'App Two',
@@ -738,6 +776,44 @@ describe('copyBaseApplicationProject', () => {
     });
   });
 
+  describe('integration test', () => {
+    it('should include vitest and test scripts in package.json when enabled', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const packageJson = await fs.readJson(
+        join(testAppDirectory, 'package.json'),
+      );
+
+      expect(packageJson.scripts.test).toBe('vitest run');
+      expect(packageJson.scripts['test:watch']).toBe('vitest');
+      expect(packageJson.devDependencies.vitest).toBeDefined();
+    });
+
+    it('should not include vitest or test scripts when disabled', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: NO_EXAMPLES,
+      });
+
+      const packageJson = await fs.readJson(
+        join(testAppDirectory, 'package.json'),
+      );
+
+      expect(packageJson.scripts.test).toBeUndefined();
+      expect(packageJson.scripts['test:watch']).toBeUndefined();
+      expect(packageJson.devDependencies.vitest).toBeUndefined();
+    });
+  });
+
   describe('post-install logic function', () => {
     it('should create post-install.ts with definePostInstallLogicFunction and typed payload', async () => {
       await copyBaseApplicationProject({

packages/create-twenty-app/src/utils/__tests__/test-template.spec.ts

@@ -0,0 +1,144 @@
+import { scaffoldIntegrationTest } from '@/utils/test-template';
+import * as fs from 'fs-extra';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+describe('scaffoldIntegrationTest', () => {
+  let testAppDirectory: string;
+  let sourceFolderPath: string;
+
+  beforeEach(async () => {
+    testAppDirectory = join(
+      tmpdir(),
+      `test-twenty-app-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    sourceFolderPath = join(testAppDirectory, 'src');
+    await fs.ensureDir(sourceFolderPath);
+
+    await fs.writeJson(join(testAppDirectory, 'tsconfig.json'), {
+      compilerOptions: {
+        paths: { 'src/*': ['./src/*'] },
+      },
+      exclude: ['node_modules', 'dist', '**/*.integration-test.ts'],
+    });
+  });
+
+  afterEach(async () => {
+    if (testAppDirectory && (await fs.pathExists(testAppDirectory))) {
+      await fs.remove(testAppDirectory);
+    }
+  });
+
+  describe('integration test file', () => {
+    it('should create app-install.integration-test.ts with correct structure', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const testPath = join(
+        sourceFolderPath,
+        '__tests__',
+        'app-install.integration-test.ts',
+      );
+
+      expect(await fs.pathExists(testPath)).toBe(true);
+
+      const content = await fs.readFile(testPath, 'utf8');
+
+      expect(content).toContain(
+        "import { appBuild, appUninstall } from 'twenty-sdk/cli'",
+      );
+      expect(content).toContain(
+        "import { MetadataApiClient } from 'twenty-sdk/generated'",
+      );
+      expect(content).toContain(
+        "import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'",
+      );
+      expect(content).toContain('TWENTY_TEST_API_KEY');
+      expect(content).toContain('assertServerIsReachable');
+      expect(content).toContain('appBuild');
+      expect(content).toContain('appUninstall');
+      expect(content).toContain('findManyApplications');
+      expect(content).toContain('APPLICATION_UNIVERSAL_IDENTIFIER');
+    });
+  });
+
+  describe('setup-test file', () => {
+    it('should create setup-test.ts with SDK config bootstrap', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const setupTestPath = join(
+        sourceFolderPath,
+        '__tests__',
+        'setup-test.ts',
+      );
+
+      expect(await fs.pathExists(setupTestPath)).toBe(true);
+
+      const content = await fs.readFile(setupTestPath, 'utf8');
+
+      expect(content).toContain('.twenty-sdk-test');
+      expect(content).toContain('config.json');
+      expect(content).toContain('process.env.TWENTY_API_URL');
+      expect(content).toContain('process.env.TWENTY_TEST_API_KEY');
+    });
+  });
+
+  describe('vitest config', () => {
+    it('should create vitest.config.ts with env vars and setup file', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const vitestConfigPath = join(testAppDirectory, 'vitest.config.ts');
+
+      expect(await fs.pathExists(vitestConfigPath)).toBe(true);
+
+      const content = await fs.readFile(vitestConfigPath, 'utf8');
+
+      expect(content).toContain('TWENTY_TEST_API_KEY');
+      expect(content).toContain('TWENTY_API_URL');
+      expect(content).toContain('setup-test.ts');
+      expect(content).toContain('tsconfig.spec.json');
+      expect(content).toContain('integration-test.ts');
+    });
+  });
+
+  describe('tsconfig.spec.json', () => {
+    it('should create tsconfig.spec.json extending the base tsconfig', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const tsconfigSpecPath = join(testAppDirectory, 'tsconfig.spec.json');
+
+      expect(await fs.pathExists(tsconfigSpecPath)).toBe(true);
+
+      const tsconfigSpec = await fs.readJson(tsconfigSpecPath);
+
+      expect(tsconfigSpec.extends).toBe('./tsconfig.json');
+      expect(tsconfigSpec.compilerOptions.composite).toBe(true);
+      expect(tsconfigSpec.include).toContain('src/**/*.ts');
+      expect(tsconfigSpec.exclude).not.toContain('**/*.integration-test.ts');
+    });
+
+    it('should add a reference to tsconfig.spec.json in tsconfig.json', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const tsconfig = await fs.readJson(
+        join(testAppDirectory, 'tsconfig.json'),
+      );
+
+      expect(tsconfig.references).toEqual([{ path: './tsconfig.spec.json' }]);
+    });
+  });
+});

packages/create-twenty-app/src/utils/app-template.ts

@@ -1,9 +1,10 @@
 import * as fs from 'fs-extra';
 import { join } from 'path';
-import { v4 } from 'uuid';
 import { ASSETS_DIR } from 'twenty-shared/application';
+import { v4 } from 'uuid';
 
 import { type ExampleOptions } from '@/types/scaffolding-options';
+import { scaffoldIntegrationTest } from '@/utils/test-template';
 import createTwentyAppPackageJson from 'package.json';
 
 const SRC_FOLDER = 'src';
@@ -23,7 +24,11 @@ export const copyBaseApplicationProject = async ({
 }) => {
   await fs.copy(join(__dirname, './constants/base-application'), appDirectory);
 
-  await createPackageJson({ appName, appDirectory });
+  await createPackageJson({
+    appName,
+    appDirectory,
+    includeExampleIntegrationTest: exampleOptions.includeExampleIntegrationTest,
+  });
 
   await createGitignore(appDirectory);
 
@@ -98,6 +103,13 @@ export const copyBaseApplicationProject = async ({
     });
   }
 
+  if (exampleOptions.includeExampleIntegrationTest) {
+    await scaffoldIntegrationTest({
+      appDirectory,
+      sourceFolderPath,
+    });
+  }
+
   await createDefaultPreInstallFunction({
     appDirectory: sourceFolderPath,
     fileFolder: 'logic-functions',
@@ -167,6 +179,7 @@ yarn-error.log*
 
 # typescript
 *.tsbuildinfo
+*.d.ts
 `;
 
   await fs.writeFile(join(appDirectory, '.gitignore'), gitignoreContent);
@@ -509,11 +522,16 @@ const createApplicationConfig = async ({
   fileFolder?: string;
   fileName: string;
 }) => {
+  const universalIdentifier = v4();
+
   const content = `import { defineApplication } from 'twenty-sdk';
 import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
 
+export const APPLICATION_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
 export default defineApplication({
-  universalIdentifier: '${v4()}',
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
   displayName: '${displayName}',
   description: '${description ?? ''}',
   defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
@@ -527,10 +545,35 @@ export default defineApplication({
 const createPackageJson = async ({
   appName,
   appDirectory,
+  includeExampleIntegrationTest,
 }: {
   appName: string;
   appDirectory: string;
+  includeExampleIntegrationTest: boolean;
 }) => {
+  const scripts: Record<string, string> = {
+    twenty: 'twenty',
+    lint: 'eslint',
+    'lint:fix': 'eslint --fix',
+  };
+
+  const devDependencies: Record<string, string> = {
+    typescript: '^5.9.3',
+    '@types/node': '^24.7.2',
+    '@types/react': '^18.2.0',
+    react: '^18.2.0',
+    eslint: '^9.32.0',
+    'typescript-eslint': '^8.50.0',
+    'twenty-sdk': createTwentyAppPackageJson.version,
+  };
+
+  if (includeExampleIntegrationTest) {
+    scripts.test = 'vitest run';
+    scripts['test:watch'] = 'vitest';
+    devDependencies.vitest = '^3.1.1';
+    devDependencies['vite-tsconfig-paths'] = '^4.2.1';
+  }
+
   const packageJson = {
     name: appName,
     version: '0.1.0',
@@ -541,21 +584,8 @@ const createPackageJson = async ({
       yarn: '>=4.0.2',
     },
     packageManager: 'yarn@4.9.2',
-    scripts: {
-      twenty: 'twenty',
-      lint: 'eslint',
-      'lint:fix': 'eslint --fix',
-    },
-    dependencies: {},
-    devDependencies: {
-      'twenty-sdk': createTwentyAppPackageJson.version,
-      typescript: '^5.9.3',
-      '@types/node': '^24.7.2',
-      '@types/react': '^18.2.0',
-      react: '^18.2.0',
-      eslint: '^9.32.0',
-      'typescript-eslint': '^8.50.0',
-    },
+    scripts,
+    devDependencies,
   };
 
   await fs.writeFile(

packages/create-twenty-app/src/utils/test-template.ts

@@ -0,0 +1,226 @@
+import * as fs from 'fs-extra';
+import { join } from 'path';
+
+const SEED_API_KEY =
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik';
+
+export const scaffoldIntegrationTest = async ({
+  appDirectory,
+  sourceFolderPath,
+}: {
+  appDirectory: string;
+  sourceFolderPath: string;
+}) => {
+  await createIntegrationTest({
+    appDirectory: sourceFolderPath,
+    fileFolder: '__tests__',
+    fileName: 'app-install.integration-test.ts',
+  });
+
+  await createSetupTest({
+    appDirectory: sourceFolderPath,
+    fileFolder: '__tests__',
+    fileName: 'setup-test.ts',
+  });
+
+  await createVitestConfig(appDirectory);
+  await createTsconfigSpec(appDirectory);
+};
+
+const createVitestConfig = async (appDirectory: string) => {
+  const content = `import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    include: ['src/**/*.integration-test.ts'],
+    setupFiles: ['src/__tests__/setup-test.ts'],
+    env: {
+      TWENTY_API_URL: 'http://localhost:3000',
+      TWENTY_TEST_API_KEY:
+        '${SEED_API_KEY}',
+    },
+  },
+});
+`;
+
+  await fs.writeFile(join(appDirectory, 'vitest.config.ts'), content);
+};
+
+const createTsconfigSpec = async (appDirectory: string) => {
+  const tsconfigSpec = {
+    extends: './tsconfig.json',
+    compilerOptions: {
+      composite: true,
+      types: ['vitest/globals'],
+    },
+    include: ['src/**/*.ts', 'src/**/*.tsx'],
+    exclude: ['node_modules', 'dist'],
+  };
+
+  await fs.writeFile(
+    join(appDirectory, 'tsconfig.spec.json'),
+    JSON.stringify(tsconfigSpec, null, 2),
+  );
+
+  const tsconfigPath = join(appDirectory, 'tsconfig.json');
+  const tsconfig = await fs.readJson(tsconfigPath);
+
+  tsconfig.references = [{ path: './tsconfig.spec.json' }];
+
+  await fs.writeFile(tsconfigPath, JSON.stringify(tsconfig, null, 2));
+};
+
+const createSetupTest = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const content = `import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { beforeAll } from 'vitest';
+
+const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test');
+
+beforeAll(() => {
+  fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });
+
+  const configFile = {
+    profiles: {
+      default: {
+        apiUrl: process.env.TWENTY_API_URL,
+        apiKey: process.env.TWENTY_TEST_API_KEY,
+      },
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(TEST_CONFIG_DIR, 'config.json'),
+    JSON.stringify(configFile, null, 2),
+  );
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createIntegrationTest = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const content = `import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
+import { appBuild, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-sdk/generated';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const APP_PATH = process.cwd();
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:3000';
+
+const assertServerIsReachable = async () => {
+  let response: Response;
+
+  try {
+    response = await fetch(\`\${TWENTY_API_URL}/healthz\`);
+  } catch {
+    throw new Error(
+      \`Twenty server is not reachable at \${TWENTY_API_URL}. \` +
+        'Make sure the server is running before executing integration tests.',
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(\`Server at \${TWENTY_API_URL} returned \${response.status}\`);
+  }
+};
+
+describe('App installation', () => {
+  let appInstalled = false;
+
+  beforeAll(async () => {
+    await assertServerIsReachable();
+
+    const buildResult = await appBuild({
+      appPath: APP_PATH,
+      onProgress: (message: string) => console.log(\`[build] \${message}\`),
+    });
+
+    if (!buildResult.success) {
+      throw new Error(
+        \`App build failed: \${buildResult.error?.message ?? 'Unknown error'}\`,
+      );
+    }
+
+    appInstalled = true;
+  });
+
+  afterAll(async () => {
+    if (!appInstalled) {
+      return;
+    }
+
+    const uninstallResult = await appUninstall({ appPath: APP_PATH });
+
+    if (!uninstallResult.success) {
+      console.warn(
+        \`App uninstall failed: \${uninstallResult.error?.message ?? 'Unknown error'}\`,
+      );
+    }
+  });
+
+  it('should find the installed app in the applications list', async () => {
+    const apiKey = process.env.TWENTY_TEST_API_KEY;
+
+    if (!apiKey) {
+      throw new Error(
+        'No API key found. Set TWENTY_TEST_API_KEY in your vitest config env.',
+      );
+    }
+
+    const metadataClient = new MetadataApiClient({
+      url: \`\${TWENTY_API_URL}/metadata\`,
+      headers: {
+        Authorization: \`Bearer \${apiKey}\`,
+      },
+    });
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (application: { universalIdentifier: string }) =>
+        application.universalIdentifier ===
+        APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};

packages/create-twenty-app/tsconfig.json

@@ -23,5 +23,8 @@
     "**/__mocks__/**/*",
     "vite.config.ts",
     "jest.config.mjs"
+  ],
+  "exclude": [
+    "src/constants/base-application/vitest.config.ts"
   ]
 }

packages/twenty-apps/community/apollo-enrich/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn
+
+# codegen
+generated
+
+# testing
+/coverage
+
+# dev
+/dist/
+
+.twenty/*
+!.twenty/output/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# typescript
+*.tsbuildinfo

packages/twenty-apps/community/apollo-enrich/.nvmrc

@@ -0,0 +1 @@
+24.5.0

packages/twenty-apps/community/apollo-enrich/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

packages/twenty-apps/community/apollo-enrich/LLMS.md

@@ -0,0 +1,12 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+
+## UUID requirement
+- All generated UUIDs must be valid UUID v4.
+
+## Common Pitfalls
+
+- Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
+- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.

packages/twenty-apps/community/apollo-enrich/README.md

@@ -0,0 +1,51 @@
+This is a [Twenty](https://twenty.com) application project bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
+
+## Getting Started
+
+First, authenticate to your workspace:
+
+```bash
+yarn twenty auth:login
+```
+
+Then, start development mode to sync your app and watch for changes:
+
+```bash
+yarn twenty app:dev
+```
+
+Open your Twenty instance and go to `/settings/applications` section to see the result.
+
+## Available Commands
+
+Run `yarn twenty help` to list all available commands. Common commands:
+
+```bash
+# Authentication
+yarn twenty auth:login     # Authenticate with Twenty
+yarn twenty auth:logout    # Remove credentials
+yarn twenty auth:status    # Check auth status
+yarn twenty auth:switch    # Switch default workspace
+yarn twenty auth:list      # List all configured workspaces
+
+# Application
+yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty function:logs  # Stream function logs
+yarn twenty function:execute  # Execute a function with JSON payload
+yarn twenty app:uninstall  # Uninstall app from workspace
+```
+
+## LLMs instructions
+
+Main docs and pitfalls are available in LLMS.md file.
+
+## Learn More
+
+To learn more about Twenty applications, take a look at the following resources:
+
+- [twenty-sdk](https://www.npmjs.com/package/twenty-sdk) - learn about `twenty-sdk` tool.
+- [Twenty doc](https://docs.twenty.com/) - Twenty's documentation.
+- Join our [Discord](https://discord.gg/cx5n4Jzs57)
+
+You can check out [the Twenty GitHub repository](https://github.com/twentyhq/twenty) - your feedback and contributions are welcome!

packages/twenty-apps/community/apollo-enrich/eslint.config.mjs

@@ -0,0 +1,29 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+  // Base JS recommended rules
+  js.configs.recommended,
+
+  // TypeScript recommended rules
+  ...tseslint.configs.recommended,
+
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Common TypeScript-friendly tweaks
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      'no-unused-vars': 'off', // handled by TS rule
+    },
+  },
+];

packages/twenty-apps/community/apollo-enrich/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "apollo-enrich",
+  "version": "0.1.0",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.5.0",
+    "npm": "please-use-yarn",
+    "yarn": ">=4.0.2"
+  },
+  "packageManager": "yarn@4.9.2",
+  "scripts": {
+    "twenty": "twenty",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix"
+  },
+  "dependencies": {
+    "twenty-sdk": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^18.2.0",
+    "eslint": "^9.32.0",
+    "react": "^18.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0"
+  }
+}

packages/twenty-apps/community/apollo-enrich/src/application-config.ts

@@ -0,0 +1,54 @@
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { defineApplication } from 'twenty-sdk';
+
+export default defineApplication({
+  universalIdentifier: 'ac1d2ed1-8835-4bd4-9043-28b46fdda465',
+  displayName: 'Apollo enrichment',
+  description: 'Data enrichment with Apollo to keep your data accurate',
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  settingsCustomTabFrontComponentUniversalIdentifier: '50d59f7c-eada-4731-aacd-8e45371e1040',
+  applicationVariables: {
+    APOLLO_CLIENT_ID: {
+      universalIdentifier: '5852219e-7757-463e-9e7c-80980203794c',
+      isSecret: true,
+      value: '',
+      description: 'Apollo Client ID',
+    },
+    APOLLO_CLIENT_SECRET: {
+      universalIdentifier: 'a032349d-9458-4381-8505-82547276434a',
+      isSecret: true,
+      value: '',
+      description: 'Apollo Client Secret',
+    },
+    APOLLO_OAUTH_URL: {
+      universalIdentifier: '1d42411c-5809-4093-873a-8121b1302475',
+      isSecret: false,
+      value: '',
+      description: 'Apollo OAuth URL',
+    },
+    APOLLO_REDIRECT_URI: {
+      universalIdentifier: 'c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f',
+      isSecret: false,
+      value: '',
+      description: 'Apollo OAuth redirect URI',
+    },
+    APOLLO_REGISTERED_URL: {
+      universalIdentifier: '672a6fce-5565-43bc-9a3b-7f2c33620770',
+      isSecret: false,
+      value: '',
+      description: 'Apollo registered URL',
+    },
+    APOLLO_ACCESS_TOKEN: {
+      universalIdentifier: '672a6fce-5565-43bc-9a3b-7f2c33620771',
+      isSecret: true,
+      value: '',
+      description: 'Apollo access token',
+    },
+    APOLLO_REFRESH_TOKEN: {
+      universalIdentifier: '672a6fce-5565-43bc-9a3b-7f2c33620772',
+      isSecret: true,
+      value: '',
+      description: 'Apollo refresh token',
+    },
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-founded-year.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'da15cfc6-3657-457d-8757-4ba11b5bb6e1',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.NUMBER,
+  name: 'apolloFoundedYear',
+  label: 'Founded Year',
+  description: 'Year the company was founded, from Apollo enrichment',
+  icon: 'IconCalendar',
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-industry.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: '505532f5-1fc5-4a58-8074-ba9b48650dbc',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.TEXT,
+  name: 'apolloIndustry',
+  label: 'Apollo Industry',
+  description: 'Industry classification from Apollo enrichment',
+  icon: 'IconBuildingFactory',
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-short-description.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'be15e062-b065-48b4-979c-65b9a50e0cb1',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.TEXT,
+  name: 'apolloShortDescription',
+  label: 'Apollo Description',
+  description: 'Short company description from Apollo enrichment',
+  icon: 'IconFileDescription',
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-total-funding.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'c90ae72d-4ddf-4f22-882f-eef98c91e40e',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.CURRENCY,
+  name: 'apolloTotalFunding',
+  label: 'Total Funding',
+  description: 'Total funding raised by the company, from Apollo enrichment',
+  icon: 'IconCash',
+});

packages/twenty-apps/community/apollo-enrich/src/front-components/apollo-oauth-cta.tsx

@@ -0,0 +1,220 @@
+import styled from '@emotion/styled';
+import { useEffect, useState } from 'react';
+import { OAuthApplicationVariables } from 'src/logic-functions/get-oauth-application-variables';
+import { VERIFY_PAGE_PATH } from 'src/logic-functions/get-verify-page';
+import { defineFrontComponent } from 'twenty-sdk';
+
+const StyledContainer = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: 100%;
+`;
+
+const StyledSectionTitle = styled.h3`
+  color: #333;
+  font-family: 'Inter', sans-serif;
+  font-size: 15px;
+  font-weight: 600;
+  margin: 0 0 4px 0;
+`;
+
+const StyledSectionSubtitle = styled.p`
+  color: #818181;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+  font-weight: 400;
+  margin: 0 0 12px 0;
+`;
+
+const StyledCard = styled.div`
+  align-items: center;
+  background: #fff;
+  border: 1px solid #ebebeb;
+  border-radius: 8px;
+  display: flex;
+  gap: 12px;
+  padding: 16px;
+`;
+
+const StyledIconContainer = styled.div`
+  align-items: center;
+  background: #f5f5f5;
+  border-radius: 8px;
+  color: #666;
+  display: flex;
+  flex-shrink: 0;
+  height: 40px;
+  justify-content: center;
+  width: 40px;
+`;
+
+const StyledTextContainer = styled.div`
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+`;
+
+const StyledTitle = styled.span`
+  color: #333;
+  font-family: 'Inter', sans-serif;
+  font-size: 14px;
+  font-weight: 500;
+`;
+
+const StyledDescription = styled.span`
+  color: #818181;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+`;
+
+const StyledLink = styled.a`
+  align-items: center;
+  background: #5e5adb;
+  border: 1px solid rgba(0, 0, 0, 0.04);
+  border-radius: 4px;
+  box-sizing: border-box;
+  color: #fafafa;
+  cursor: pointer;
+  display: inline-flex;
+  flex-shrink: 0;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+  font-weight: 500;
+  gap: 4px;
+  height: 32px;
+  justify-content: center;
+  padding: 0 12px;
+  text-decoration: none;
+  transition: background 0.1s ease;
+  white-space: nowrap;
+
+  &:hover {
+    background: #4b47b8;
+  }
+
+  &:active {
+    background: #3c3996;
+  }
+
+  &:focus {
+    outline: none;
+  }
+`;
+
+const StyledConnectedStatus = styled.span`
+  align-items: center;
+  background: #10b981;
+  border-radius: 4px;
+  color: #fff;
+  display: inline-flex;
+  flex-shrink: 0;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+  font-weight: 500;
+  gap: 6px;
+  height: 32px;
+  padding: 0 12px;
+  white-space: nowrap;
+`;
+
+const StyledIcon = styled.img`
+  height: 24px;
+  width: 24px;
+`;
+
+const APOLLO_ICON_URL = 'https://twenty-icons.com/apollo.io';
+
+const fetchOAuthApplicationVariables = async (): Promise<OAuthApplicationVariables> => {
+  const backEndUrl = `${process.env.TWENTY_API_URL}/s/oauth/application-variables`;
+  const response = await fetch(backEndUrl, {
+    method: 'GET',
+  });
+  const data = await response.json();
+
+  return data;
+};
+
+const buildOAuthUrl = (oauthApplicationVariables: OAuthApplicationVariables): string => {
+  const { apolloOAuthUrl, apolloClientId, apolloRegisteredUrl } = oauthApplicationVariables;
+  const redirectUri = `${apolloRegisteredUrl}auth/oauth-propagator/callback`;
+  const state = encodeURIComponent(`${process.env.TWENTY_API_URL}/s${VERIFY_PAGE_PATH}`);
+  return `${apolloOAuthUrl}?client_id=${apolloClientId}&redirect_uri=${redirectUri}&state=${state}&response_type=code`;
+};
+
+const ApolloOAuthCta = () => {
+  const [oauthApplicationVariables, setOAuthApplicationVariables] =
+    useState<OAuthApplicationVariables | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    fetchOAuthApplicationVariables()
+      .then(setOAuthApplicationVariables)
+      .catch(setError)
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  if (isLoading) {
+    return (
+      <StyledContainer>
+        <StyledSectionTitle>Connect to Apollo</StyledSectionTitle>
+        <StyledSectionSubtitle>Enrich your contacts with Apollo data</StyledSectionSubtitle>
+        <StyledCard>
+          <StyledIconContainer>
+            <StyledIcon src={APOLLO_ICON_URL} alt="Apollo" />
+          </StyledIconContainer>
+          <StyledTextContainer>
+            <StyledTitle>Apollo OAuth</StyledTitle>
+            <StyledDescription>Loading...</StyledDescription>
+          </StyledTextContainer>
+        </StyledCard>
+      </StyledContainer>
+    );
+  }
+
+  if (error || !oauthApplicationVariables) {
+    return null;
+  }
+
+  const isConnected = Boolean(oauthApplicationVariables.apolloAccessToken);
+  const oauthUrl = buildOAuthUrl(oauthApplicationVariables);
+
+  return (
+    <StyledContainer>
+      <StyledSectionTitle>Connect to Apollo</StyledSectionTitle>
+      <StyledSectionSubtitle>Enrich your contacts with Apollo data</StyledSectionSubtitle>
+      <StyledCard>
+        <StyledIconContainer>
+          <StyledIcon src={APOLLO_ICON_URL} alt="Apollo" />
+        </StyledIconContainer>
+        <StyledTextContainer>
+          <StyledTitle>Apollo OAuth</StyledTitle>
+          <StyledDescription>
+            {isConnected
+              ? 'Your Apollo account is connected'
+              : 'Connect your Apollo account to enrich contacts'}
+          </StyledDescription>
+        </StyledTextContainer>
+        {isConnected ? (
+          <StyledConnectedStatus>
+            ✓ Connected
+          </StyledConnectedStatus>
+        ) : (
+          <StyledLink href={oauthUrl} rel="noopener noreferrer">
+            Connect
+          </StyledLink>
+        )}
+      </StyledCard>
+    </StyledContainer>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '50d59f7c-eada-4731-aacd-8e45371e1040',
+  name: 'apollo-oauth-cta',
+  description: 'CTA button to connect to Apollo Enrichment via OAuth',
+  component: ApolloOAuthCta,
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-authentication-token-pairs.ts

@@ -0,0 +1,105 @@
+import { defineLogicFunction, RoutePayload } from "twenty-sdk";
+import { MetadataApiClient } from 'twenty-sdk/generated';
+
+
+export const OAUTH_TOKEN_PAIRS_PATH = '/oauth/token-pairs';
+
+type ApolloTokenResponse = {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token: string;
+  scope: string;
+  created_at: number;
+};
+
+const getAuthenticationTokenPairs = async (
+  code: string,
+  clientId: string,
+  clientSecret: string,
+): Promise<ApolloTokenResponse> => {
+  const formData = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: clientId,
+    client_secret: clientSecret,
+    code: code,
+    redirect_uri: 'https://hjsm0q38-3000.uks1.devtunnels.ms/auth/oauth-propagator/callback',
+  });
+
+  const response = await fetch('https://app.apollo.io/api/v1/oauth/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: formData.toString(),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Failed to exchange code for tokens: ${response.status} - ${errorText}`);
+  }
+
+  return response.json();
+};
+
+const handler = async (event: RoutePayload): Promise<any> => {
+  const { queryStringParameters: { code } } = event;
+
+  if (!code) {
+    throw new Error('Code is required');
+  }
+
+  const apolloClientId = process.env.APOLLO_CLIENT_ID ?? '';
+  const apolloClientSecret = process.env.APOLLO_CLIENT_SECRET ?? '';
+  const applicationId = process.env.APPLICATION_ID ?? '';
+
+
+  const metadataClient = new MetadataApiClient({});
+
+
+
+
+
+
+
+
+  const tokenPairs = await getAuthenticationTokenPairs(
+    code,
+    apolloClientId,
+    apolloClientSecret,
+  );
+
+  await metadataClient.mutation({
+    updateOneApplicationVariable: {
+      __args: {
+          key: 'APOLLO_ACCESS_TOKEN',
+          value: tokenPairs.access_token,
+          applicationId,
+        },
+    },
+  });
+
+   await metadataClient.mutation({
+    updateOneApplicationVariable: {
+      __args: {
+          key: 'APOLLO_REFRESH_TOKEN',
+          value: tokenPairs.refresh_token,
+          applicationId,
+        },
+    },
+  });
+  return {tokenPairs};
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '7ccc63a7-ece1-44c0-adbe-805a1baea03a',
+  name: 'get-authentication-token-pairs',
+  description: 'Returns the Apollo authentication token pairs',
+  timeoutSeconds: 10,
+  handler,
+  httpRouteTriggerSettings: {
+    path: OAUTH_TOKEN_PAIRS_PATH,
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-oauth-application-variables.ts

@@ -0,0 +1,32 @@
+import { defineLogicFunction } from 'twenty-sdk';
+
+export type OAuthApplicationVariables = {
+  apolloClientId: string;
+  apolloRegisteredUrl: string;
+  apolloOAuthUrl: string;
+  apolloAccessToken: string;
+  apolloRefreshToken: string;
+};
+
+const handler = async (): Promise<OAuthApplicationVariables> => {
+  const apolloClientId = process.env.APOLLO_CLIENT_ID ?? '';
+  const apolloRegisteredUrl = process.env.APOLLO_REGISTERED_URL ?? '';
+  const apolloOAuthUrl = process.env.APOLLO_OAUTH_URL ?? '';
+  const apolloAccessToken = process.env.APOLLO_ACCESS_TOKEN ?? '';
+  const apolloRefreshToken = process.env.APOLLO_REFRESH_TOKEN ?? '';
+
+  return { apolloClientId, apolloRegisteredUrl, apolloOAuthUrl, apolloAccessToken, apolloRefreshToken };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'b7c3e8f1-9d4a-4e2b-8f6c-1a5d3e7b9c2f',
+  name: 'get-oauth-application-variables',
+  description: 'Returns the Apollo OAuth authorization URL',
+  timeoutSeconds: 10,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/oauth/application-variables',
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-verify-page.ts

@@ -0,0 +1,90 @@
+import { defineLogicFunction } from "twenty-sdk";
+
+export const VERIFY_PAGE_PATH = '/oauth/verify';
+
+const buildVerifyPageHtml = (applicationId: string): string => `<!DOCTYPE html>
+<html>
+<head>
+  <title>Apollo OAuth - Verifying...</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; text-align: center; }
+    .loading { color: #6b7280; }
+    .success { color: #10b981; }
+    .error { color: #ef4444; }
+    .spinner { border: 3px solid #f3f4f6; border-top: 3px solid #3b82f6; border-radius: 50%; width: 40px; height: 40px; animation: spin 1s linear infinite; margin: 20px auto; }
+    @keyframes spin { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } }
+  </style>
+  <script>
+    (async function() {
+      const applicationId = ${JSON.stringify(applicationId)};
+      const urlParams = new URLSearchParams(window.location.search);
+      const code = urlParams.get('code');
+      const baseUrl = window.location.origin;
+
+      function showError(message) {
+        document.addEventListener('DOMContentLoaded', function() {
+          document.getElementById('spinner').style.display = 'none';
+          document.getElementById('title').textContent = '✗ Connection Failed';
+          document.getElementById('title').className = 'error';
+          document.getElementById('status').textContent = message;
+        });
+
+        if (window.opener) {
+          window.opener.postMessage({ type: 'APOLLO_OAUTH_ERROR', error: message }, '*');
+        }
+      }
+
+      if (!code) {
+        showError('Authorization code is missing. Please try connecting again.');
+        return;
+      }
+
+      try {
+        const response = await fetch(
+          baseUrl + '/s/oauth/token-pairs?code=' + encodeURIComponent(code),
+          {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' }
+          }
+        );
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error('Failed to get tokens: ' + response.status + ' - ' + errorText);
+        }
+
+        const tokens = await response.json();
+
+        window.location.href = 'http://apple.localhost:3001/settings/applications/' + applicationId + '#custom';
+
+      } catch (error) {
+        showError(error.message);
+      }
+    })();
+  </script>
+</head>
+<body>
+  <div class="spinner" id="spinner"></div>
+  <h1 class="loading" id="title">Connecting to Apollo...</h1>
+  <p id="status">Please wait while we complete the connection.</p>
+</body>
+</html>`;
+
+const handler = async (): Promise<string> => {
+  const applicationId = process.env.APPLICATION_ID ?? '';
+
+  return buildVerifyPageHtml(applicationId);
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '4d74950a-d9c1-4c66-a799-89c1aea4e6b0',
+  name: 'get-verify-page',
+  description: 'Returns the Apollo OAuth verify page',
+  timeoutSeconds: 10,
+  handler,
+  httpRouteTriggerSettings: {
+    path: VERIFY_PAGE_PATH,
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/on-company-updated.ts

@@ -0,0 +1,234 @@
+import {
+  defineLogicFunction,
+  type DatabaseEventPayload,
+  type ObjectRecordUpdateEvent,
+} from 'twenty-sdk';
+import { CoreApiClient } from 'twenty-sdk/generated';
+
+
+
+type CompanyRecord = {
+  id: string;
+  name?: string;
+  domainName?: {
+    primaryLinkUrl?: string;
+    primaryLinkLabel?: string;
+  };
+};
+
+type ApolloOrganization = {
+  name?: string;
+  website_url?: string;
+  linkedin_url?: string;
+  twitter_url?: string;
+  estimated_num_employees?: number;
+  annual_revenue?: number;
+  total_funding?: number;
+  street_address?: string;
+  city?: string;
+  state?: string;
+  postal_code?: string;
+  country?: string;
+  short_description?: string;
+  industry?: string;
+  founded_year?: number;
+};
+
+type ApolloEnrichResponse = {
+  organization?: ApolloOrganization;
+};
+
+
+
+const extractDomain = (
+  domainName?: CompanyRecord['domainName'],
+): string | undefined => {
+  const url = domainName?.primaryLinkUrl;
+
+  if (!url) {
+    return undefined;
+  }
+
+  try {
+    const hostname = new URL(
+      url.startsWith('http') ? url : `https://${url}`,
+    ).hostname;
+
+    return hostname.replace(/^www\./, '');
+  } catch {
+    return url.replace(/^(https?:\/\/)?(www\.)?/, '').split('/')[0];
+  }
+};
+
+const fetchApolloEnrichment = async (
+  domain: string,
+): Promise<ApolloOrganization | undefined> => {
+  const response = await fetch(
+    `https://api.apollo.io/api/v1/organizations/enrich?domain=${encodeURIComponent(domain)}`,
+    {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.APOLLO_ACCESS_TOKEN ?? ''}`,
+      },
+    },
+  );
+
+  const data: ApolloEnrichResponse = await response.json();
+
+  return data.organization;
+};
+
+const buildCompanyUpdateData = (
+  apolloOrganization: ApolloOrganization,
+): Record<string, unknown> => {
+  const updateData: Record<string, unknown> = {};
+
+  if (apolloOrganization.name) {
+    updateData.name = apolloOrganization.name;
+  }
+
+  if (apolloOrganization.estimated_num_employees) {
+    updateData.employees = apolloOrganization.estimated_num_employees;
+  }
+
+  if (apolloOrganization.linkedin_url) {
+    updateData.linkedinLink = {
+      primaryLinkUrl: apolloOrganization.linkedin_url,
+      primaryLinkLabel: 'LinkedIn',
+    };
+  }
+
+  if (apolloOrganization.twitter_url) {
+    updateData.xLink = {
+      primaryLinkUrl: apolloOrganization.twitter_url,
+      primaryLinkLabel: 'X',
+    };
+  }
+
+  if (apolloOrganization.annual_revenue) {
+    updateData.annualRecurringRevenue = {
+      amountMicros: apolloOrganization.annual_revenue * 1_000_000,
+      currencyCode: 'USD',
+    };
+  }
+
+  const hasAddress =
+    apolloOrganization.street_address ||
+    apolloOrganization.city ||
+    apolloOrganization.state ||
+    apolloOrganization.country;
+
+  if (hasAddress) {
+    updateData.address = {
+      addressStreet1: apolloOrganization.street_address ?? '',
+      addressCity: apolloOrganization.city ?? '',
+      addressState: apolloOrganization.state ?? '',
+      addressPostcode: apolloOrganization.postal_code ?? '',
+      addressCountry: apolloOrganization.country ?? '',
+    };
+  }
+
+  if (apolloOrganization.industry) {
+    updateData.apolloIndustry = apolloOrganization.industry;
+  }
+
+  if (apolloOrganization.short_description) {
+    updateData.apolloShortDescription = apolloOrganization.short_description;
+  }
+
+  if (apolloOrganization.founded_year) {
+    updateData.apolloFoundedYear = apolloOrganization.founded_year;
+  }
+
+  if (apolloOrganization.total_funding) {
+    updateData.apolloTotalFunding = {
+      amountMicros: apolloOrganization.total_funding * 1_000_000,
+      currencyCode: 'USD',
+    };
+  }
+
+  return updateData;
+};
+
+const updateCompanyInTwenty = async (
+  companyId: string,
+  updateData: Record<string, unknown>,
+): Promise<void> => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    updateCompany: {
+      __args: {
+        id: companyId,
+        data: updateData,
+      },
+      id: true,
+    },
+  });
+
+  if (!result.updateCompany) {
+    throw new Error(`Failed to update company ${companyId}: no result`);
+  }
+};
+
+
+type CompanyUpdateEvent = DatabaseEventPayload<
+  ObjectRecordUpdateEvent<CompanyRecord>
+>;
+
+const handler = async (
+  event: CompanyUpdateEvent,
+): Promise<object | undefined> => {
+
+
+    const { recordId, properties } = event;
+    const { after: companyAfter } = properties;
+
+    const domain = extractDomain(companyAfter?.domainName);
+
+    if (!domain) {
+      return { skipped: true, reason: 'no domain found on company' };
+    }
+
+    const apolloOrganization = await fetchApolloEnrichment(domain);
+
+    if (!apolloOrganization) {
+      return {
+        skipped: true,
+        reason: `no Apollo data found for ${domain}`,
+      };
+    }
+
+    const updateData = buildCompanyUpdateData(apolloOrganization);
+
+    if (Object.keys(updateData).length === 0) {
+      return { skipped: true, reason: 'no enrichment data to apply' };
+    }
+
+
+    await updateCompanyInTwenty(recordId, updateData);
+
+    const result = {
+      enriched: true,
+      companyId: recordId,
+      domain,
+      updatedFields: Object.keys(updateData),
+    };
+
+    return result;
+
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '6248b3fe-a8af-404a-8e38-19df98f73d81',
+  name: 'on-company-updated',
+  description:
+    'Enriches company data from Apollo when the company domain is updated',
+  timeoutSeconds: 30,
+  handler,
+  databaseEventTriggerSettings: {
+    eventName: 'company.updated',
+    updatedFields: ['domainName'],
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/post-install.ts

@@ -0,0 +1,13 @@
+import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: '08292efc-d7ba-4ec3-ab95-e7c33bd3a3bc',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/pre-install.ts

@@ -0,0 +1,13 @@
+import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'af7cd86e-149e-466a-8d60-312b6e46d604',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});

packages/twenty-apps/community/apollo-enrich/src/roles/default-role.ts

@@ -0,0 +1,15 @@
+import { defineRole } from 'twenty-sdk';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b8faae3f-e174-43fa-ab94-715712ae26cb';
+
+export default defineRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Apollo enrich default function role',
+  description: 'Apollo enrich default function role',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: true,
+  canSoftDeleteAllObjectRecords: true,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: true,
+});

packages/twenty-apps/community/apollo-enrich/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "sourceMap": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "jsx": "react-jsx",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "allowUnreachableCode": false,
+    "strict": true,
+    "alwaysStrict": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": false,
+    "target": "es2018",
+    "module": "esnext",
+    "lib": ["es2020", "dom"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "resolveJsonModule": true,
+    "paths": {
+      "src/*": ["./src/*"],
+      "~/*": ["./*"]
+    }
+  },
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

packages/twenty-apps/hello-world/.env.example

@@ -1,2 +0,0 @@
-TWENTY_API_KEY=<SET_YOUR_TWENTY_API_KEY>
-TWENTY_API_URL=<SET_YOUR_TWENTY_API_URL>

packages/twenty-apps/hello-world/.gitignore

@@ -1,2 +1,38 @@
-.yarn/install-state.gz
-.env
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn
+
+# codegen
+generated
+
+# testing
+/coverage
+
+# dev
+/dist/
+
+.twenty
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# typescript
+*.tsbuildinfo
+*.d.ts

packages/twenty-apps/hello-world/.nvmrc

@@ -0,0 +1 @@
+24.5.0

packages/twenty-apps/hello-world/LLMS.md

@@ -0,0 +1,12 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+
+## UUID requirement
+- All generated UUIDs must be valid UUID v4.
+
+## Common Pitfalls
+
+- Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
+- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.

packages/twenty-apps/hello-world/README.md

@@ -1,41 +1,62 @@
-# Hello world
+This is a [Twenty](https://twenty.com) application project bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
 
-A minimal hello-world application built with an alpha version of the twenty-cli.
+## Getting Started
 
-⚠️ Since this project uses an early alpha release, expect breaking changes and evolving features.
-
-This example will gradually gain complexity and capabilities as the twenty-cli matures with future updates.
-
-
-## Requirements
-- twenty-cli `npm install -g twenty-cli`
-- an `apiKey`. Go to `/settings/api-webhooks` to generate one
-
-
-## Install to your Twenty workspace
+First, authenticate to your workspace:
 
 ```bash
-cp .env.example .env
+yarn twenty auth:login
 ```
 
-- replace `<SET_YOUR_TWENTY_API_KEY>` and `<SET_YOUR_TWENTY_API_URL>` accordingly
+Then, start development mode to sync your app and watch for changes:
 
 ```bash
-twenty auth login
-twenty app sync
+yarn twenty app:dev
 ```
 
-## What it does
-- creates a new object `postCard` with a `name` field
-- creates a serverless function `create-new-post-card`
-- two triggers on `create-new-post-card`:
-  - one route trigger on `GET` `/post-card/create?recipient=RecipientName`
-  - one databaseEvent trigger on `people.created` events
+Open your Twenty instance and go to `/settings/applications` section to see the result.
 
-## Development
+## Available Commands
 
-Run dev mode and see application updates on your workspace instantly
+Run `yarn twenty help` to list all available commands. Common commands:
 
 ```bash
-twenty app dev
+# Authentication
+yarn twenty auth:login     # Authenticate with Twenty
+yarn twenty auth:logout    # Remove credentials
+yarn twenty auth:status    # Check auth status
+yarn twenty auth:switch    # Switch default workspace
+yarn twenty auth:list      # List all configured workspaces
+
+# Application
+yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty function:logs  # Stream function logs
+yarn twenty function:execute  # Execute a function with JSON payload
+yarn twenty app:uninstall  # Uninstall app from workspace
 ```
+
+## Integration Tests
+
+If your project includes the example integration test (`src/__tests__/app-install.integration-test.ts`), you can run it with:
+
+```bash
+# Make sure a Twenty server is running at http://localhost:3000
+yarn test
+```
+
+The test builds and installs the app, then verifies it appears in the applications list. Test configuration (API URL and API key) is defined in `vitest.config.ts`.
+
+## LLMs instructions
+
+Main docs and pitfalls are available in LLMS.md file.
+
+## Learn More
+
+To learn more about Twenty applications, take a look at the following resources:
+
+- [twenty-sdk](https://www.npmjs.com/package/twenty-sdk) - learn about `twenty-sdk` tool.
+- [Twenty doc](https://docs.twenty.com/) - Twenty's documentation.
+- Join our [Discord](https://discord.gg/cx5n4Jzs57)
+
+You can check out [the Twenty GitHub repository](https://github.com/twentyhq/twenty) - your feedback and contributions are welcome!

packages/twenty-apps/hello-world/eslint.config.mjs

@@ -0,0 +1,29 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+  // Base JS recommended rules
+  js.configs.recommended,
+
+  // TypeScript recommended rules
+  ...tseslint.configs.recommended,
+
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Common TypeScript-friendly tweaks
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      'no-unused-vars': 'off', // handled by TS rule
+    },
+  },
+];

packages/twenty-apps/hello-world/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "hello-world",
+  "name": "@twentyhq/hello-world",
   "version": "0.2.2",
   "license": "MIT",
   "engines": {
@@ -9,16 +9,21 @@
   },
   "packageManager": "yarn@4.9.2",
   "scripts": {
-    "create-entity": "twenty app add",
-    "dev": "twenty app dev",
-    "sync": "twenty app sync",
-    "uninstall": "twenty app uninstall",
-    "auth": "twenty auth login"
-  },
-  "dependencies": {
-    "twenty-sdk": "0.2.4"
+    "twenty": "twenty",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
-    "@types/node": "^24.7.2"
+    "@types/node": "^24.7.2",
+    "@types/react": "^18.2.0",
+    "eslint": "^9.32.0",
+    "react": "^18.2.0",
+    "twenty-sdk": "0.6.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0",
+    "vite-tsconfig-paths": "^4.2.1",
+    "vitest": "^3.1.1"
   }
 }

packages/twenty-apps/hello-world/src/__tests__/app-install.integration-test.ts

@@ -0,0 +1,92 @@
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
+import { appBuild, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-sdk/generated';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const APP_PATH = process.cwd();
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:3000';
+
+const assertServerIsReachable = async () => {
+  let response: Response;
+
+  try {
+    response = await fetch(`${TWENTY_API_URL}/healthz`);
+  } catch {
+    throw new Error(
+      `Twenty server is not reachable at ${TWENTY_API_URL}. ` +
+        'Make sure the server is running before executing integration tests.',
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(`Server at ${TWENTY_API_URL} returned ${response.status}`);
+  }
+};
+
+describe('App installation', () => {
+  let appInstalled = false;
+
+  beforeAll(async () => {
+    await assertServerIsReachable();
+
+    const buildResult = await appBuild({
+      appPath: APP_PATH,
+      onProgress: (message: string) => console.log(`[build] ${message}`),
+    });
+
+    if (!buildResult.success) {
+      throw new Error(
+        `App build failed: ${buildResult.error?.message ?? 'Unknown error'}`,
+      );
+    }
+
+    appInstalled = true;
+  });
+
+  afterAll(async () => {
+    if (!appInstalled) {
+      return;
+    }
+
+    const uninstallResult = await appUninstall({ appPath: APP_PATH });
+
+    if (!uninstallResult.success) {
+      console.warn(
+        `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,
+      );
+    }
+  });
+
+  it('should find the installed app in the applications list', async () => {
+    const apiKey = process.env.TWENTY_TEST_API_KEY;
+
+    if (!apiKey) {
+      throw new Error(
+        'No API key found. Set TWENTY_TEST_API_KEY in your vitest config env.',
+      );
+    }
+
+    const metadataClient = new MetadataApiClient({
+      url: `${TWENTY_API_URL}/metadata`,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (application: { universalIdentifier: string }) =>
+        application.universalIdentifier ===
+        APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});

packages/twenty-apps/hello-world/src/__tests__/setup-test.ts

@@ -0,0 +1,24 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { beforeAll } from 'vitest';
+
+const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test');
+
+beforeAll(() => {
+  fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });
+
+  const configFile = {
+    profiles: {
+      default: {
+        apiUrl: process.env.TWENTY_API_URL,
+        apiKey: process.env.TWENTY_TEST_API_KEY,
+      },
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(TEST_CONFIG_DIR, 'config.json'),
+    JSON.stringify(configFile, null, 2),
+  );
+});

packages/twenty-apps/hello-world/src/actions/create-new-post-card.ts

@@ -1,67 +0,0 @@
-import type {
-  FunctionConfig,
-  DatabaseEventPayload,
-  ObjectRecordCreateEvent,
-  CronPayload,
-} from 'twenty-sdk';
-import Twenty, { type Person } from '../../generated';
-
-type CreateNewPostCardParams =
-  | { name?: string }
-  | DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
-  | CronPayload;
-
-export const main = async (params: CreateNewPostCardParams) => {
-  try {
-    const client = new Twenty();
-
-    const name =
-      'name' in params
-        ? params.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
-        : 'Hello world';
-
-    const createPostCard = await client.mutation({
-      createPostCard: {
-        __args: {
-          data: {
-            name,
-          },
-        },
-        name: true,
-        id: true,
-      },
-    });
-
-    console.log('createPostCard result', createPostCard);
-
-    return createPostCard;
-  } catch (error) {
-    console.error(error);
-    throw error;
-  }
-};
-
-export const config: FunctionConfig = {
-  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
-  name: 'create-new-post-card',
-  timeoutSeconds: 2,
-  triggers: [
-    {
-      universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
-      type: 'route',
-      path: '/post-card/create',
-      httpMethod: 'GET',
-      isAuthRequired: false,
-    },
-    {
-      universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
-      type: 'cron',
-      pattern: '0 0 1 1 *', // Every year 1st of January
-    },
-    {
-      universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
-      type: 'databaseEvent',
-      eventName: 'person.created',
-    },
-  ],
-};

packages/twenty-apps/hello-world/src/application-config.ts

@@ -0,0 +1,12 @@
+import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+
+export const APPLICATION_UNIVERSAL_IDENTIFIER =
+  '1badae7c-8a42-4dea-b4b8-3c56e77c2f9a';
+
+export default defineApplication({
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  displayName: 'Hello world',
+  description: '',
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+});

packages/twenty-apps/hello-world/src/application.config.ts

@@ -1,19 +0,0 @@
-import { type ApplicationConfig } from 'twenty-sdk';
-
-const config: ApplicationConfig = {
-  universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
-  displayName: 'Hello World',
-  description: 'A simple hello world app',
-  icon: 'IconWorld',
-  applicationVariables: {
-    DEFAULT_RECIPIENT_NAME: {
-      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
-      description: 'Default recipient name for postcards',
-      value: 'Alex Karp',
-      isSecret: false,
-    },
-  },
-  defaultRoleUniversalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
-};
-
-export default config;

packages/twenty-apps/hello-world/src/fields/example-field.ts

@@ -0,0 +1,11 @@
+import { defineField, FieldType } from 'twenty-sdk';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+
+export default defineField({
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: '2c503a0d-36c9-49ec-b82f-4fafe0eb6f47',
+  type: FieldType.NUMBER,
+  name: 'priority',
+  label: 'Priority',
+  description: 'Priority level for the example item (1-10)',
+});

packages/twenty-apps/hello-world/src/front-components/hello-world.tsx

@@ -0,0 +1,17 @@
+import { defineFrontComponent } from 'twenty-sdk';
+
+export const HelloWorld = () => {
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>Hello, World!</h1>
+      <p>This is your first front component.</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '26c17445-fbfb-4b34-99d6-f461e734ca97',
+  name: 'hello-world-front-component',
+  description: 'A sample front component',
+  component: HelloWorld,
+});

packages/twenty-apps/hello-world/src/logic-functions/hello-world.ts

@@ -0,0 +1,18 @@
+import { defineLogicFunction } from 'twenty-sdk';
+
+const handler = async (): Promise<{ message: string }> => {
+  return { message: 'Hello, World!' };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '4f0b7137-1399-4e50-ac00-3c3bb2555c38',
+  name: 'hello-world-logic-function',
+  description: 'A simple logic function',
+  timeoutSeconds: 5,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/hello-world-logic-function',
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/hello-world/src/logic-functions/post-install.ts

@@ -0,0 +1,13 @@
+import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'c1410017-8536-42aa-a188-4bfc5a1c3dae',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});

packages/twenty-apps/hello-world/src/logic-functions/pre-install.ts

@@ -0,0 +1,13 @@
+import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: '68d005d4-1110-4fa0-8227-71e06d6b9f30',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});

packages/twenty-apps/hello-world/src/navigation-menu-items/example-navigation-menu-item.ts

@@ -0,0 +1,14 @@
+import { defineNavigationMenuItem } from 'twenty-sdk';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '574a895f-1511-4b38-9d28-d6b8436738ff',
+  name: 'example-navigation-menu-item',
+  icon: 'IconList',
+  position: 0,
+  // Link to a view:
+  // viewUniversalIdentifier: '...',
+  // Or link to an object:
+  // targetObjectUniversalIdentifier: '...',
+  // Or link to an external URL:
+  // link: 'https://example.com',
+});

packages/twenty-apps/hello-world/src/objects/example-object.ts

@@ -0,0 +1,28 @@
+import { defineObject, FieldType } from 'twenty-sdk';
+
+export const EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER =
+  'b75cfe84-18ce-47da-812a-53e25ee094af';
+
+export const NAME_FIELD_UNIVERSAL_IDENTIFIER =
+  '6ab9c690-06ce-455e-a2c9-8067a9747f96';
+
+export default defineObject({
+  universalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  nameSingular: 'exampleItem',
+  namePlural: 'exampleItems',
+  labelSingular: 'Example item',
+  labelPlural: 'Example items',
+  description: 'A sample custom object',
+  icon: 'IconBox',
+  labelIdentifierFieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+  fields: [
+    {
+      universalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.TEXT,
+      name: 'name',
+      label: 'Name',
+      description: 'Name of the example item',
+      icon: 'IconAbc',
+    },
+  ],
+});

packages/twenty-apps/hello-world/src/objects/postCard.ts

@@ -1,112 +0,0 @@
-import { type Note } from '../../generated';
-
-import {
-  type AddressField,
-  Field,
-  FieldType,
-  type FullNameField,
-  Object,
-  OnDeleteAction,
-  Relation,
-  RelationType,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-
-enum PostCardStatus {
-  DRAFT = 'DRAFT',
-  SENT = 'SENT',
-  DELIVERED = 'DELIVERED',
-  RETURNED = 'RETURNED',
-}
-
-@Object({
-  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
-  nameSingular: 'postCard',
-  namePlural: 'postCards',
-  labelSingular: 'Post card',
-  labelPlural: 'Post cards',
-  description: ' A post card object',
-  icon: 'IconMail',
-})
-export class PostCard {
-  @Field({
-    universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
-    type: FieldType.TEXT,
-    label: 'Content',
-    description: "Postcard's content",
-    icon: 'IconAbc',
-  })
-  content: string;
-
-  @Field({
-    universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
-    type: FieldType.FULL_NAME,
-    label: 'Recipient name',
-    icon: 'IconUser',
-  })
-  recipientName: FullNameField;
-
-  @Field({
-    universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
-    type: FieldType.ADDRESS,
-    label: 'Recipient address',
-    icon: 'IconHome',
-  })
-  recipientAddress: AddressField;
-
-  @Field({
-    universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
-    type: FieldType.SELECT,
-    label: 'Status',
-    icon: 'IconSend',
-    defaultValue: `'${PostCardStatus.DRAFT}'`,
-    options: [
-      {
-        value: PostCardStatus.DRAFT,
-        label: 'Draft',
-        position: 0,
-        color: 'gray',
-      },
-      {
-        value: PostCardStatus.SENT,
-        label: 'Sent',
-        position: 1,
-        color: 'orange',
-      },
-      {
-        value: PostCardStatus.DELIVERED,
-        label: 'Delivered',
-        position: 2,
-        color: 'green',
-      },
-      {
-        value: PostCardStatus.RETURNED,
-        label: 'Returned',
-        position: 3,
-        color: 'orange',
-      },
-    ],
-  })
-  status: PostCardStatus;
-
-  @Relation({
-    universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
-    type: RelationType.ONE_TO_MANY,
-    label: 'Notes',
-    icon: 'IconComment',
-    inverseSideTargetUniversalIdentifier:
-      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note.universalIdentifier,
-    onDelete: OnDeleteAction.CASCADE,
-  })
-  notes: Note[];
-
-  @Field({
-    universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
-    type: FieldType.DATE_TIME,
-    label: 'Delivered at',
-    icon: 'IconCheck',
-    isNullable: true,
-    defaultValue: null,
-  })
-  deliveredAt?: Date;
-}

packages/twenty-apps/hello-world/src/roles/default-role.ts

@@ -0,0 +1,14 @@
+import { defineRole } from 'twenty-sdk';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'f14afc30-f2fa-4f70-9b12-903c5f852225';
+
+export default defineRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Hello world default function role',
+  description: 'Hello world default function role',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: true,
+  canSoftDeleteAllObjectRecords: true,
+  canDestroyAllObjectRecords: false,
+});

packages/twenty-apps/hello-world/src/roles/function-role.ts

@@ -1,33 +0,0 @@
-import { PermissionFlag, type RoleConfig } from 'twenty-sdk';
-
-export const functionRole: RoleConfig = {
-  universalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
-  label: 'Default function role',
-  description: 'Default role for function Twenty client',
-  canReadAllObjectRecords: false,
-  canUpdateAllObjectRecords: false,
-  canSoftDeleteAllObjectRecords: false,
-  canDestroyAllObjectRecords: false,
-  canUpdateAllSettings: false,
-  canBeAssignedToAgents: false,
-  canBeAssignedToUsers: false,
-  canBeAssignedToApiKeys: false,
-  objectPermissions: [
-    {
-      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
-      canReadObjectRecords: true,
-      canUpdateObjectRecords: true,
-      canSoftDeleteObjectRecords: false,
-      canDestroyObjectRecords: false,
-    },
-  ],
-  fieldPermissions: [
-    {
-      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
-      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
-      canReadFieldValue: false,
-      canUpdateFieldValue: false,
-    },
-  ],
-  permissionFlags: [PermissionFlag.APPLICATIONS],
-};

packages/twenty-apps/hello-world/src/skills/example-skill.ts

@@ -0,0 +1,13 @@
+import { defineSkill } from 'twenty-sdk';
+
+export const EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER =
+  '4f00dd76-c07b-4d55-a43a-7f17e7f6440a';
+
+export default defineSkill({
+  universalIdentifier: EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER,
+  name: 'example-skill',
+  label: 'Example Skill',
+  description: 'A sample skill for your application',
+  icon: 'IconBrain',
+  content: 'Add your skill instructions here. Skills provide context and capabilities to AI agents.',
+});

packages/twenty-apps/hello-world/src/views/example-view.ts

@@ -0,0 +1,10 @@
+import { defineView } from 'twenty-sdk';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+
+export default defineView({
+  universalIdentifier: 'e574b32c-c058-492a-8a5c-780b844a8735',
+  name: 'example-view',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconList',
+  position: 0,
+});

packages/twenty-apps/hello-world/tsconfig.json

@@ -5,21 +5,45 @@
     "declaration": true,
     "outDir": "./dist",
     "rootDir": ".",
+    "jsx": "react-jsx",
     "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
     "emitDecoratorMetadata": true,
     "experimentalDecorators": true,
     "importHelpers": true,
     "allowUnreachableCode": false,
-    "strictNullChecks": true,
+    "strict": true,
     "alwaysStrict": true,
     "noImplicitAny": true,
     "strictBindCallApply": false,
     "target": "es2018",
     "module": "esnext",
-    "lib": ["es2020", "dom"],
+    "lib": [
+      "es2020",
+      "dom"
+    ],
     "skipLibCheck": true,
     "skipDefaultLibCheck": true,
     "resolveJsonModule": true,
+    "paths": {
+      "src/*": [
+        "./src/*"
+      ],
+      "~/*": [
+        "./*"
+      ]
+    }
   },
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
-}
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.integration-test.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

packages/twenty-apps/hello-world/tsconfig.spec.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "types": [
+      "vitest/globals"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

packages/twenty-apps/hello-world/vitest.config.ts

@@ -0,0 +1,22 @@
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    include: ['src/**/*.integration-test.ts'],
+    setupFiles: ['src/__tests__/setup-test.ts'],
+    env: {
+      TWENTY_API_URL: 'http://localhost:3000',
+      TWENTY_TEST_API_KEY:
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik',
+    },
+  },
+});

packages/twenty-apps/internal/call-recording/.gitignore

@@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn
+
+# codegen
+generated
+
+# testing
+/coverage
+
+# dev
+/dist/
+
+.twenty/*
+!.twenty/output/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# typescript
+*.tsbuildinfo
+
+
+# Remove once prod ready
+.twenty

packages/twenty-apps/internal/call-recording/.nvmrc

@@ -0,0 +1 @@
+24.5.0

packages/twenty-apps/internal/call-recording/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

packages/twenty-apps/internal/call-recording/LLMS.md

@@ -0,0 +1,9 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+
+## Common Pitfalls
+
+- Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
+- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.

packages/twenty-apps/internal/call-recording/README.md

@@ -0,0 +1,51 @@
+This is a [Twenty](https://twenty.com) application project bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
+
+## Getting Started
+
+First, authenticate to your workspace:
+
+```bash
+yarn twenty auth:login
+```
+
+Then, start development mode to sync your app and watch for changes:
+
+```bash
+yarn twenty app:dev
+```
+
+Open your Twenty instance and go to `/settings/applications` section to see the result.
+
+## Available Commands
+
+Run `yarn twenty help` to list all available commands. Common commands:
+
+```bash
+# Authentication
+yarn twenty auth:login     # Authenticate with Twenty
+yarn twenty auth:logout    # Remove credentials
+yarn twenty auth:status    # Check auth status
+yarn twenty auth:switch    # Switch default workspace
+yarn twenty auth:list      # List all configured workspaces
+
+# Application
+yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty function:logs  # Stream function logs
+yarn twenty function:execute  # Execute a function with JSON payload
+yarn twenty app:uninstall  # Uninstall app from workspace
+```
+
+## LLMs instructions
+
+Main docs and pitfalls are available in LLMS.md file.
+
+## Learn More
+
+To learn more about Twenty applications, take a look at the following resources:
+
+- [twenty-sdk](https://www.npmjs.com/package/twenty-sdk) - learn about `twenty-sdk` tool.
+- [Twenty doc](https://docs.twenty.com/) - Twenty's documentation.
+- Join our [Discord](https://discord.gg/cx5n4Jzs57)
+
+You can check out [the Twenty GitHub repository](https://github.com/twentyhq/twenty) - your feedback and contributions are welcome!

packages/twenty-apps/internal/call-recording/eslint.config.mjs

@@ -0,0 +1,29 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+  // Base JS recommended rules
+  js.configs.recommended,
+
+  // TypeScript recommended rules
+  ...tseslint.configs.recommended,
+
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Common TypeScript-friendly tweaks
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      'no-unused-vars': 'off', // handled by TS rule
+    },
+  },
+];

packages/twenty-apps/internal/call-recording/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "call-recording",
+  "version": "0.1.0",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.5.0",
+    "npm": "please-use-yarn",
+    "yarn": ">=4.0.2"
+  },
+  "packageManager": "yarn@4.9.2",
+  "scripts": {
+    "twenty": "twenty",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix"
+  },
+  "dependencies": {
+    "@emotion/react": "^11.11.1",
+    "@emotion/styled": "^11.11.0",
+    "react-loading-skeleton": "^3.5.0",
+    "react-markdown": "^10.1.0",
+    "twenty-sdk": "0.6.3-alpha"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^18.2.0",
+    "eslint": "^9.32.0",
+    "react": "^18.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0"
+  }
+}

packages/twenty-apps/internal/call-recording/src/application-config.ts

@@ -0,0 +1,9 @@
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { defineApplication } from 'twenty-sdk';
+
+export default defineApplication({
+  universalIdentifier: '4daa5147-7e70-4e43-b091-c27e1e8a32e3',
+  displayName: 'Call recording',
+  description: 'Allows to record calls',
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+});