The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Move app tooling consumers to the standalone CLI (#28182)
Weiko10e5adf62082
diff --git a/.github/actions/deploy-twenty-app/action.yml b/.github/actions/deploy-twenty-app/action.ymlindex ba2fc54602c..734dc6c758b 100644--- a/.github/actions/deploy-twenty-app/action.yml+++ b/.github/actions/deploy-twenty-app/action.yml@@ -8,6 +8,10 @@ inputs:api-key:description: API key or access token for the target instancerequired: true+ cli-version:+ description: Exact Twenty CLI version, ignored when TWENTY_CLI points to a local build+ required: false+ default: '2.49.0'app-path:description: Path to the app directory (relative to repo root). Defaults to repo root.required: false@@ -32,22 +36,27 @@ runs:working-directory: ${{ inputs.app-path }}run: yarn install --immutable- - name: Configure remote+ - name: Install Twenty CLI+ if: env.TWENTY_CLI == ''shell: bash- run: |- mkdir -p ~/.twenty- node -e "- const fs = require('fs'), path = require('path'), os = require('os');- fs.writeFileSync(path.join(os.homedir(), '.twenty', 'config.json'), JSON.stringify({- version: 1,- remotes: { target: { apiUrl: process.env.API_URL, apiKey: process.env.API_KEY, twentyCLIAccessToken: process.env.API_KEY } }- }, null, 2));- "env:- API_URL: ${{ inputs.api-url }}- API_KEY: ${{ inputs.api-key }}+ TWENTY_CLI_VERSION: ${{ inputs.cli-version }}+ run: |+ if [ -z "$TWENTY_CLI_VERSION" ]; then+ echo "::error::Set cli-version to an exact released Twenty CLI version, or set TWENTY_CLI to a local build."+ exit 1+ fi+ npm install -g "twenty@$TWENTY_CLI_VERSION"- name: Deployshell: bashworking-directory: ${{ inputs.app-path }}- run: yarn twenty app:publish --private --remote target+ env:+ TWENTY_API_URL: ${{ inputs.api-url }}+ TWENTY_API_KEY: ${{ inputs.api-key }}+ run: |+ if [ -n "${TWENTY_CLI:-}" ]; then+ node "$TWENTY_CLI" app publish --private+ else+ twenty app publish --private+ fidiff --git a/.github/actions/install-twenty-app/action.yml b/.github/actions/install-twenty-app/action.ymlindex 44b284a3e38..ba3b719451e 100644--- a/.github/actions/install-twenty-app/action.yml+++ b/.github/actions/install-twenty-app/action.yml@@ -8,6 +8,10 @@ inputs:api-key:description: API key or access token for the target workspacerequired: true+ cli-version:+ description: Exact Twenty CLI version, ignored when TWENTY_CLI points to a local build+ required: false+ default: '2.49.0'app-path:description: Path to the app directory (relative to repo root). Defaults to repo root.required: false@@ -32,22 +36,27 @@ runs:working-directory: ${{ inputs.app-path }}run: yarn install --immutable- - name: Configure remote+ - name: Install Twenty CLI+ if: env.TWENTY_CLI == ''shell: bash- run: |- mkdir -p ~/.twenty- node -e "- const fs = require('fs'), path = require('path'), os = require('os');- fs.writeFileSync(path.join(os.homedir(), '.twenty', 'config.json'), JSON.stringify({- version: 1,- remotes: { target: { apiUrl: process.env.API_URL, apiKey: process.env.API_KEY, twentyCLIAccessToken: process.env.API_KEY } }- }, null, 2));- "env:- API_URL: ${{ inputs.api-url }}- API_KEY: ${{ inputs.api-key }}+ TWENTY_CLI_VERSION: ${{ inputs.cli-version }}+ run: |+ if [ -z "$TWENTY_CLI_VERSION" ]; then+ echo "::error::Set cli-version to an exact released Twenty CLI version, or set TWENTY_CLI to a local build."+ exit 1+ fi+ npm install -g "twenty@$TWENTY_CLI_VERSION"- name: Installshell: bashworking-directory: ${{ inputs.app-path }}- run: yarn twenty app:install --remote target+ env:+ TWENTY_API_URL: ${{ inputs.api-url }}+ TWENTY_API_KEY: ${{ inputs.api-key }}+ run: |+ if [ -n "${TWENTY_CLI:-}" ]; then+ node "$TWENTY_CLI" app install+ else+ twenty app install+ fidiff --git a/.github/actions/test-twenty-app/action.yml b/.github/actions/test-twenty-app/action.ymlindex be958b7c07c..17098a9f047 100644--- a/.github/actions/test-twenty-app/action.yml+++ b/.github/actions/test-twenty-app/action.yml@@ -40,6 +40,15 @@ runs:;;esac+ - name: Install monorepo dependencies+ uses: ./.github/actions/yarn-install++ - name: Build Twenty CLI from checkout+ shell: bash+ run: |+ npx nx build twenty-cli+ echo "TWENTY_CLI=$GITHUB_WORKSPACE/packages/twenty-cli/dist/cli.cjs" >> "$GITHUB_ENV"+- name: Enable Corepackif: inputs.mode == 'installation-and-integration-test' || inputs.mode == 'integration-test-only'shell: bashdiff --git a/.github/workflows/ci-cli.yaml b/.github/workflows/ci-cli.yamlindex 1d85da9f8cf..e58cda3f4d7 100644--- a/.github/workflows/ci-cli.yaml+++ b/.github/workflows/ci-cli.yaml@@ -65,17 +65,17 @@ jobs:uses: ./.github/actions/restore-cachewith:key: cli-test- - name: Build the CLI and the SDK used by parity tests+ - name: Build the CLI and SDK authoring exportsrun: npx nx run-many --target=build --projects=twenty-sdk,twenty-cli- name: Lintrun: npx nx lint twenty-cli- name: Typecheckrun: npx tsgo -p packages/twenty-cli/tsconfig.json --noEmit- name: Unit tests- run: npx vitest run --maxWorkers=2 --exclude src/app/manifest/__tests__/manifest-parity.spec.ts+ run: npx vitest run --maxWorkers=2 --exclude src/app/manifest/__tests__/manifest-fixtures.spec.tsworking-directory: packages/twenty-cli- - name: Manifest parity tests- run: npx vitest run --maxWorkers=1 src/app/manifest/__tests__/manifest-parity.spec.ts+ - name: Manifest fixture tests+ run: npx vitest run --maxWorkers=1 src/app/manifest/__tests__/manifest-fixtures.spec.tsworking-directory: packages/twenty-cli- name: Test app publishing with an isolated local registryrun: |diff --git a/.github/workflows/ci-example-app-hello-world.yaml b/.github/workflows/ci-example-app-hello-world.yamlindex 93e1feaa90e..101271b00f9 100644--- a/.github/workflows/ci-example-app-hello-world.yaml+++ b/.github/workflows/ci-example-app-hello-world.yaml@@ -21,6 +21,7 @@ jobs:files: |packages/twenty-apps/examples/hello-world/**packages/twenty-sdk/**+ packages/twenty-cli/**packages/twenty-client-sdk/**packages/twenty-shared/**!packages/twenty-sdk/package.json@@ -50,6 +51,7 @@ jobs:ports:- 6379:6379env:+ TWENTY_CLI: ${{ github.workspace }}/packages/twenty-cli/dist/cli.cjsTWENTY_API_URL: http://localhost:3000TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdiksteps:@@ -62,6 +64,9 @@ jobs:- name: Build SDK packagesrun: npx nx build twenty-sdk+ - name: Build CLI+ run: npx nx build twenty-cli+- name: Setup server environmentrun: npx nx reset:env:e2e-testing-server twenty-server@@ -79,6 +84,10 @@ jobs:- name: Wait for server to be readyrun: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000+ - name: Start worker+ working-directory: packages/twenty-server+ run: nohup yarn worker:prod > /tmp/twenty-worker.log 2>&1 &+- name: Run integration testsworking-directory: packages/twenty-apps/examples/hello-worldrun: npx vitest rundiff --git a/.github/workflows/ci-example-app-postcard.yaml b/.github/workflows/ci-example-app-postcard.yamlindex 26f2434e9be..16067831277 100644--- a/.github/workflows/ci-example-app-postcard.yaml+++ b/.github/workflows/ci-example-app-postcard.yaml@@ -21,6 +21,7 @@ jobs:files: |packages/twenty-apps/examples/postcard/**packages/twenty-sdk/**+ packages/twenty-cli/**packages/twenty-client-sdk/**packages/twenty-shared/**packages/twenty-server/**@@ -52,6 +53,7 @@ jobs:ports:- 6379:6379env:+ TWENTY_CLI: ${{ github.workspace }}/packages/twenty-cli/dist/cli.cjsTWENTY_API_URL: http://localhost:3000TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdiksteps:@@ -64,6 +66,9 @@ jobs:- name: Build SDK packagesrun: npx nx build twenty-sdk+ - name: Build CLI+ run: npx nx build twenty-cli+- name: Setup server environmentrun: npx nx reset:env:e2e-testing-server twenty-server@@ -81,34 +86,21 @@ jobs:- name: Wait for server to be readyrun: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000+ - name: Start worker+ working-directory: packages/twenty-server+ run: nohup yarn worker:prod > /tmp/twenty-worker.log 2>&1 &+- name: Run integration testsworking-directory: packages/twenty-apps/examples/postcardrun: npx vitest run- - name: Configure remote for SDK CLI- run: |- mkdir -p ~/.twenty- cat > ~/.twenty/config.json <<EOF- {- "version": 1,- "remotes": {- "target": {- "apiUrl": "${TWENTY_API_URL}",- "apiKey": "${TWENTY_API_KEY}",- "twentyCLIAccessToken": "${TWENTY_API_KEY}"- }- },- "defaultRemote": "target"- }- EOF-- name: Deploy postcard app (registry install path)working-directory: packages/twenty-apps/examples/postcard- run: node ${{ github.workspace }}/packages/twenty-sdk/dist/cli.cjs deploy --remote target+ run: node ${{ github.workspace }}/packages/twenty-cli/dist/cli.cjs app publish --private- name: Install postcard app (registry install path)working-directory: packages/twenty-apps/examples/postcard- run: node ${{ github.workspace }}/packages/twenty-sdk/dist/cli.cjs install --remote target+ run: node ${{ github.workspace }}/packages/twenty-cli/dist/cli.cjs app installci-example-app-postcard-status-check:if: always() && !cancelled()diff --git a/packages/twenty-agent-skills/README.md b/packages/twenty-agent-skills/README.mdindex c1d73e7236a..216bded5524 100644--- a/packages/twenty-agent-skills/README.md+++ b/packages/twenty-agent-skills/README.md@@ -38,7 +38,7 @@ For a checkout or an unpublished change, use the local marketplace instructions| Skill | Use it for || ---------------------------------------------------- | ------------------------------------------------------------------------------------- |-| [`create-app`](./skills/create-app/SKILL.md) | Scaffold a new Twenty app with `create-twenty-app`. |+| [`create-app`](./skills/create-app/SKILL.md) | Scaffold a new Twenty app with `twenty app init`. || [`develop-app`](./skills/develop-app/SKILL.md) | Add or modify objects, fields, logic functions, layouts, front components, workflows. || [`manage-app`](./skills/manage-app/SKILL.md) | Manage remotes, sync, build, deploy, logs, troubleshooting, CI/CD. || [`publish-app`](./skills/publish-app/SKILL.md) | Prepare README, marketplace metadata, logos, screenshots, public assets. |diff --git a/packages/twenty-agent-skills/references/concepts/how-apps-work.md b/packages/twenty-agent-skills/references/concepts/how-apps-work.mdindex 68c5ac197df..df479fafdeb 100644--- a/packages/twenty-agent-skills/references/concepts/how-apps-work.md+++ b/packages/twenty-agent-skills/references/concepts/how-apps-work.md@@ -12,10 +12,10 @@ The app does not run as a separate server. It is built, published, and installedA Twenty app depends on two SDK packages:-| Package | Purpose | Used in |-| --- | --- | --- |-| `twenty-sdk` | Define app entities and access front component runtime APIs | Entity definitions (`twenty-sdk/define`), front component hooks and host APIs (`twenty-sdk/front-component`) |-| `twenty-client-sdk` | Access workspace data from front components | Core object queries (`twenty-client-sdk/core`), metadata queries (`twenty-client-sdk/metadata`) |+| Package | Purpose | Used in |+| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |+| `twenty-sdk` | Define app entities and access front component runtime APIs | Entity definitions (`twenty-sdk/define`), front component hooks and host APIs (`twenty-sdk/front-component`) |+| `twenty-client-sdk` | Access workspace data from front components | Core object queries (`twenty-client-sdk/core`), metadata queries (`twenty-client-sdk/metadata`) |`twenty-sdk/define` provides the registration functions: `defineApplication`, `defineObject`, `defineField`, `defineView`, `definePageLayout`, `defineFrontComponent`, `defineSettingsMenuItem`, `defineNavigationMenuItem`, `defineLogicFunction`, `defineRole`, and others. Every app entity is declared through one of these functions.@@ -29,19 +29,15 @@ Twenty UI components (`Button`, `Chip`, `Tag`, `Status`, `Heading`, `Section`, `A Twenty instance is a running Twenty server — either self-hosted or managed cloud. Each instance hosts one or more workspaces. Apps are installed per workspace.-A "remote" is the local CLI's connection to a Twenty instance. It stores the server URL and an API key in `~/.twenty/config.json`. You can configure multiple remotes (e.g. `local`, `staging`, `production`) and switch between them.+A "remote" is the local CLI's connection to a Twenty instance. The standalone CLI stores its server URL and credentials locally. You can configure multiple remotes (e.g. `local`, `staging`, `production`) and switch between them.The API key authenticates the developer against the target workspace. It determines which workspace the app syncs to, deploys to, and reads data from during development.## Local Development Environment-An app needs a running Twenty instance to develop against. There are two ways to connect:+Connect to an existing Twenty workspace with `twenty auth login --url <twenty-instance-url> --name dev`. This opens browser authentication and saves a remote.-1. **Existing instance via OAuth** (default): `create-twenty-app --url <twenty-instance-url>` authenticates via OAuth on the provided Twenty server. The scaffolder opens a browser for the OAuth flow, then stores the credentials as a remote in `~/.twenty/config.json`. This is best when the developer already has a workspace with data to develop against.--2. **Local instance with Docker** (fallback): `create-twenty-app` (no `--url`) starts a disposable local Twenty server on `http://localhost:2020` through Docker. The scaffolder authenticates with the local server's development API key and creates a `local` remote automatically. Use this when the developer has no Twenty instance available and wants to start fresh without affecting a shared workspace.--In both cases, the result is a remote stored in `~/.twenty/config.json` that the CLI uses for all subsequent sync, deploy, and data access commands.+For local development, provision a separate Twenty server through Docker or the repository's development environment, then authenticate against its URL. The standalone CLI does not start containers.## App Lifecycle@@ -51,20 +47,20 @@ The development loop is:create → develop → sync → validate → repeat```-1. **Create**: `npx create-twenty-app@latest <app-name>` generates the project, installs dependencies, starts a local Twenty server, and runs an initial sync. The scaffolder handles everything in one command — do not run `yarn twenty apply` after scaffolding because the sync already happened.+1. **Create**: `twenty app init <app-name>` generates source files. Then install dependencies with `yarn install`, authenticate with `twenty auth login`, and explicitly run `twenty app apply --create` for the first sync.2. **Develop**: Add or modify entities in `src/`. Objects go in `src/objects/`, front components in `src/front-components/`, logic functions in `src/logic-functions/`, page layouts in `src/page-layouts/`, and so on. Each entity file exports a `define*` call.-3. **Sync**: `yarn twenty apply` builds, deploys, and installs the app on the active remote in one step. The Twenty instance updates its schema, registers new objects and fields, mounts front components, and activates logic functions. This is the primary way to get changes onto a Twenty instance during development. Sync after every meaningful change.+3. **Sync**: `twenty app apply` builds, deploys, and installs the app on the active remote in one step. The Twenty instance updates its schema, registers new objects and fields, mounts front components, and activates logic functions. This is the primary way to get changes onto a Twenty instance during development. Sync after every meaningful change.-4. **Validate**: `yarn twenty dev:typecheck` checks generated types. `yarn lint` checks local lint rules. Open the workspace in a browser to verify front components render and logic functions execute.+4. **Validate**: `twenty app typecheck` checks generated types. `yarn lint` checks local lint rules. Open the workspace in a browser to verify front components render and logic functions execute.## Sharing An AppPublishing is separate from the development loop. It is used to share an app with other Twenty instances or the public marketplace:-- `yarn twenty app:publish` publishes to npm for the public marketplace.-- `yarn twenty app:publish --private --remote <name>` publishes privately to a specific Twenty instance's registry.+- `twenty app publish` publishes to npm for the public marketplace.+- `twenty app publish --private --remote <name>` publishes privately to a specific Twenty instance's registry.Each publish requires a strictly higher semver version in `package.json`. See the `publish-app` skill for marketplace metadata and listing guidance.@@ -73,6 +69,7 @@ Each publish requires a strictly higher semver version in `package.json`. See thFront components do not run as a separate frontend application. The Twenty workspace renders them inside an isolated Remote DOM container. The SDK mounts the component, provides a `ThemeProvider`, and proxies host APIs (navigation, snackbars, side panels) through `twenty-sdk/front-component`.This means:+- Front components cannot access `document` or `window` globals directly.- They cannot use React portals or third-party libraries that manipulate the DOM outside their tree.- They import UI primitives from `twenty-ui` (installed from npm), not from external component libraries.@@ -110,7 +107,7 @@ my-app/## Key Concepts- **Universal identifiers**: Stable UUIDs assigned to every entity. They survive renames, version bumps, and resyncs. Never change a universal identifier after first sync.-- **Remotes**: Named connections to Twenty instances. Stored in `~/.twenty/config.json`. Switch with `yarn twenty remote:use <name>`.-- **Sync**: `yarn twenty apply` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.-- **Publish**: `yarn twenty app:publish` packages the app for distribution to other instances or the marketplace. Requires a strictly higher semver version than the previously published version.+- **Remotes**: Named connections to Twenty instances. Stored in `~/.twenty/config.json`. Switch with `twenty remote use <name>`.+- **Sync**: `twenty app apply` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.+- **Publish**: `twenty app publish` packages the app for distribution to other instances or the marketplace. Requires a strictly higher semver version than the previously published version.- **Reserved variable names**: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` are set by Twenty for every logic function run. A manifest that declares one of them as an application or server variable is rejected on sync and publish.diff --git a/packages/twenty-agent-skills/references/concepts/operating-rules.md b/packages/twenty-agent-skills/references/concepts/operating-rules.mdindex 0238df0c37f..c30650688f4 100644--- a/packages/twenty-agent-skills/references/concepts/operating-rules.md+++ b/packages/twenty-agent-skills/references/concepts/operating-rules.md@@ -4,9 +4,9 @@ These rules apply to every Twenty app task, in every skill and every agent harneThis file is the single source of truth for the cross-skill rules. Harness-specific entry points link here instead of restating them, so the rules cannot drift between distributions.-1. **Bounded sync only.** Use `yarn twenty apply` to synchronize app changes. Never `yarn twenty dev` (watch mode). Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.+1. **Bounded sync only.** Use `twenty app apply` to synchronize app changes. Never `twenty app dev` (watch mode). Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.-2. **Do not run broad validation unless it is requested.** After scaffolding (`create-twenty-app`) or after the CLI generates entities, prefer the bounded command that matches the task: `yarn twenty apply` for app sync, the package's unit-test script for unit tests, and `TWENTY_API_URL=http://localhost:2021 yarn test` for the full integration suite. Integration tests must target the isolated test instance on port `2021`, not the dev instance on port `2020`, unless the user explicitly asks otherwise.+2. **Do not run broad validation unless it is requested.** After scaffolding (`twenty app init`) or after the CLI generates entities, prefer the bounded command that matches the task: `twenty app apply` for app sync, the package's unit-test script for unit tests, and `TWENTY_API_URL=http://localhost:2021 yarn test` for the full integration suite. Integration tests must target the isolated test instance on port `2021`, not the dev instance on port `2020`, unless the user explicitly asks otherwise.3. **Generate new entities with a CLI.** A CLI produces the file structure, identifiers, SDK imports and boilerplate. Hand-craft an entity file only to modify an existing one, or when no option below can produce it. Take the first option that works:1. **The standalone `twenty` CLI, when `command -v twenty` finds it.** Run it directly, not through `yarn`. It works with or without a terminal: with `--no-input` it never prompts and exits with code 2 when a required value is missing. It covers objects, fields, logic functions and front components. For an object, pass the three `--create-*` flags so it also generates the table view, navigation menu item and record page layout that make the object visible in the UI:@@ -18,8 +18,8 @@ This file is the single source of truth for the cross-skill rules. Harness-specitwenty app add front-component --name invoice-panel --no-input```- 2. **`yarn twenty dev:add <entityType>`, in an interactive terminal only.** It covers every entity type, but it prompts for each value: in an agent's shell it fails at once with `User force closed the prompt`.- 3. **Neither runs, and the user is available**: ask them to run the exact `yarn twenty dev:add <entityType>` command in their own terminal. For an object, prefer this over writing four files by hand.+ 2. **The CLI is missing**: install the standalone `twenty` package, or ask the user to install it when their environment requires that. Do not fall back to the deprecated SDK CLI.+ 3. **The entity type is unsupported**: use the corresponding `define*` export directly. The standalone CLI currently generates objects, fields, logic functions and front components.4. **Otherwise, write the file by hand.** Follow the example on the matching docs page (append `.md` to its URL), or an existing file of the same kind in the app, check it against the types exported by `twenty-sdk/define`, and generate every identifier with `crypto.randomUUID()` instead of inventing one.4. **Confirm destructive operations.** Deploys to production, uninstalls, production remote changes, and production syncs require explicit user confirmation before execution. Treat `--remote production` as user-visible.diff --git a/packages/twenty-agent-skills/references/develop-app/app-structure.md b/packages/twenty-agent-skills/references/develop-app/app-structure.mdindex 5572e4f0e71..8d419ee0723 100644--- a/packages/twenty-agent-skills/references/develop-app/app-structure.md+++ b/packages/twenty-agent-skills/references/develop-app/app-structure.md@@ -36,7 +36,7 @@ find public -maxdepth 2 -type f | sortPrefer the app CLI for new entities when interactive prompts are acceptable:```bash-yarn twenty dev:add+twenty app add```Check first for the standalone `twenty` CLI (`command -v twenty`): `twenty app add ... --no-input` works without a terminal, and for objects the `--create-view --create-navigation-menu-item --create-page-layout` flags add the UI definitions. Rule 3 of the operating rules gives the full order of options.@@ -64,12 +64,16 @@ Every helper, type, and client file exports exactly one thing. The rule counts e```ts// ❌ Bad — src/utils/parse-company.util.ts exports a type and a utilexport type ParsedCompany = { id: string; name: string };-export const parseCompany = (raw: RawCompany): ParsedCompany => { /* ... */ };+export const parseCompany = (raw: RawCompany): ParsedCompany => {+ /* ... */+};// ✅ Good — src/utils/parse-company.util.ts (one export; the type is local)type ParsedCompany = { id: string; name: string };-export const parseCompany = (raw: RawCompany): ParsedCompany => { /* ... */ };+export const parseCompany = (raw: RawCompany): ParsedCompany => {+ /* ... */+};// ✅ Good — when the type is shared, split it// src/types/parsed-company.ts (one PascalCase type)@@ -78,7 +82,9 @@ export type ParsedCompany = { id: string; name: string };// src/utils/parse-company.util.ts (one util)import { type ParsedCompany } from 'src/types/parsed-company';-export const parseCompany = (raw: RawCompany): ParsedCompany => { /* ... */ };+export const parseCompany = (raw: RawCompany): ParsedCompany => {+ /* ... */+};```Entity files are consistent with this rule: front components, logic functions, and post-install hooks use a single `export default define...()`, which is one export.@@ -100,12 +106,12 @@ Read secrets through the application-config helper, not raw `process.env`.Once all edits for the change are complete, run lint and typecheck once at the end (not after each individual edit), then sync the app to verify the definitions are valid:```bash-yarn twenty dev:typecheck+twenty app typecheckyarn lint-yarn twenty apply+twenty app apply```-`yarn twenty dev:typecheck` checks generated app types and `yarn lint` checks local lint rules. `yarn twenty apply` then builds the app and pushes entity definitions to the active remote; if any definition is invalid, the sync reports the error. Run all three a single time once every edit is done, not repeatedly after each step.+`twenty app typecheck` checks generated app types and `yarn lint` checks local lint rules. `twenty app apply` then builds the app and pushes entity definitions to the active remote; if any definition is invalid, the sync reports the error. Run all three a single time once every edit is done, not repeatedly after each step.When the user explicitly asks to run tests, follow `tests.md`: unit tests may use the package's unit-test script, and the full suite must run with `TWENTY_API_URL=http://localhost:2021` against the isolated test instance.diff --git a/packages/twenty-agent-skills/references/develop-app/data-model.md b/packages/twenty-agent-skills/references/develop-app/data-model.mdindex 0fdbfbefb8d..84415991a25 100644--- a/packages/twenty-agent-skills/references/develop-app/data-model.md+++ b/packages/twenty-agent-skills/references/develop-app/data-model.md@@ -8,7 +8,7 @@ Objects and fields define the records users will create, view, search, and automWhen adding or modifying data model entities:-- Prefer generated app entity patterns from `yarn twenty dev:add`.+- Prefer generated app entity patterns from `twenty app add`.- Use clear object and field names that map to user-facing language.- Add relations only when users need to navigate or report across records.- Avoid duplicating data that already exists on core Twenty objects.@@ -95,7 +95,7 @@ For select fields, default values must be quoted string expressions like `"'PLAN### Relations-A relation is two `FieldType.RELATION` fields that point at each other through `relationTargetFieldMetadataUniversalIdentifier`, one on each object. The `MANY_TO_ONE` side must set `universalSettings.joinColumnName` (the convention is `<fieldName>Id`); the build rejects a `MANY_TO_ONE` relation without one. `yarn twenty dev:add field` emits it, but the reverse `ONE_TO_MANY` field still has to be written by hand, including on a standard object such as Company:+A relation is two `FieldType.RELATION` fields that point at each other through `relationTargetFieldMetadataUniversalIdentifier`, one on each object. The `MANY_TO_ONE` side must set `universalSettings.joinColumnName` (the convention is `<fieldName>Id`); the build rejects a `MANY_TO_ONE` relation without one. `twenty app add field` emits it, but the reverse `ONE_TO_MANY` field still has to be written by hand, including on a standard object such as Company:```ts// src/fields/company-on-contract.tsdiff --git a/packages/twenty-agent-skills/references/develop-app/logic.md b/packages/twenty-agent-skills/references/develop-app/logic.mdindex bc4b9762dba..c5051ce18ef 100644--- a/packages/twenty-agent-skills/references/develop-app/logic.md+++ b/packages/twenty-agent-skills/references/develop-app/logic.md@@ -77,7 +77,7 @@ When adding AI behavior:- Keep instructions grounded in available app data and tools.- State when the agent should ask for missing workspace or record context.- Avoid exposing raw IDs, timestamps, or nested API output to end users when a readable answer is possible.-- A `defineAgent` `roleUniversalIdentifier` must reference a role the app defines, and the application role (`defineApplicationRole` or `defaultRoleUniversalIdentifier`) must cover every permission that agent role grants. The build and `yarn twenty apply` fail otherwise, listing the excess grants.+- A `defineAgent` `roleUniversalIdentifier` must reference a role the app defines, and the application role (`defineApplicationRole` or `defaultRoleUniversalIdentifier`) must cover every permission that agent role grants. The build and `twenty app apply` fail otherwise, listing the excess grants.## Inbox Messages@@ -115,7 +115,7 @@ Do not write fields Twenty computes elsewhere (workflow `statuses` is computed fDev sync skips install hooks. Invoke locally:```bash-yarn twenty dev:function:exec+twenty app exec```Run again after rebuilding to verify idempotency.diff --git a/packages/twenty-agent-skills/references/develop-app/standalone-pages.md b/packages/twenty-agent-skills/references/develop-app/standalone-pages.mdindex b08388934bb..b02c18c946e 100644--- a/packages/twenty-agent-skills/references/develop-app/standalone-pages.md+++ b/packages/twenty-agent-skills/references/develop-app/standalone-pages.md@@ -21,13 +21,13 @@ The current model is:Use these surfaces for different jobs:-| Surface | Use it for | Primary app entity |-| --- | --- | --- |-| Standalone page | A full workspace page that is not tied to one record | `STANDALONE_PAGE` + `PAGE_LAYOUT` navigation item + `FRONT_COMPONENT` widget |-| Record page layout | Tabs and widgets for one object record | `RECORD_PAGE` page layout or page layout tab |-| Dashboard | Metric and report composition from built-in widgets | `DASHBOARD` page layout |-| Command or side panel | Short actions, focused forms, one selected record, or background commands | `defineFrontComponent` plus command menu item |-| Settings menu item | Configuration the app's admins set up, as a tab on the app's page under Settings > Apps, see `layout.md` | `defineFrontComponent` plus `defineSettingsMenuItem` |+| Surface | Use it for | Primary app entity |+| --------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |+| Standalone page | A full workspace page that is not tied to one record | `STANDALONE_PAGE` + `PAGE_LAYOUT` navigation item + `FRONT_COMPONENT` widget |+| Record page layout | Tabs and widgets for one object record | `RECORD_PAGE` page layout or page layout tab |+| Dashboard | Metric and report composition from built-in widgets | `DASHBOARD` page layout |+| Command or side panel | Short actions, focused forms, one selected record, or background commands | `defineFrontComponent` plus command menu item |+| Settings menu item | Configuration the app's admins set up, as a tab on the app's page under Settings > Apps, see `layout.md` | `defineFrontComponent` plus `defineSettingsMenuItem` |## Removing The Scaffolded Placeholder@@ -63,9 +63,7 @@ import { defineFrontComponent } from 'twenty-sdk/define';import { Heading } from 'twenty-ui/primitives/typography';import { themeCssVariables } from 'twenty-ui/theme';-import {- MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,-} from '../constants/universal-identifiers';+import { MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../constants/universal-identifiers';const MissionControl = () => {return (@@ -93,10 +91,7 @@ export default defineFrontComponent({``````ts src/page-layouts/mission-control.page-layout.ts-import {- definePageLayout,- PageLayoutTabLayoutMode,-} from 'twenty-sdk/define';+import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';import {MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,@@ -138,9 +133,7 @@ import {NavigationMenuItemType,} from 'twenty-sdk/define';-import {- MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,-} from '../constants/universal-identifiers';+import { MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER } from '../constants/universal-identifiers';export default defineNavigationMenuItem({universalIdentifier: '61d44a63-16e8-4fbe-bccb-9c220d44fdb9',@@ -340,9 +333,7 @@ import { Heading } from 'twenty-ui/primitives/typography';import { themeCssVariables } from 'twenty-ui/theme';const KnownGoodStandalonePage = () => (- <main- style={{ minHeight: '100%', padding: themeCssVariables.spacing[4] }}- >+ <main style={{ minHeight: '100%', padding: themeCssVariables.spacing[4] }}><Heading level={1}>Standalone page runtime is working</Heading></main>);@@ -355,7 +346,7 @@ If this renders but the full page does not, the issue is inside the full componeUse bounded apply for deployment and verification. Use `../manage-app/cli-and-sync.md` for exact command behavior, remote setup, verbose troubleshooting, deploys, and logs.```bash-yarn twenty apply+twenty app apply```Install and update flow:diff --git a/packages/twenty-agent-skills/references/develop-app/tests.md b/packages/twenty-agent-skills/references/develop-app/tests.mdindex f8096f6a684..e9baa66ec17 100644--- a/packages/twenty-agent-skills/references/develop-app/tests.md+++ b/packages/twenty-agent-skills/references/develop-app/tests.md@@ -1,6 +1,6 @@# Tests-Tests use the `*.spec.ts` extension and live in sibling `__tests__/` folders next to the code they cover, matching Twenty backend conventions. Write them where `yarn twenty apply` does not validate correctness.+Tests use the `*.spec.ts` extension and live in sibling `__tests__/` folders next to the code they cover, matching Twenty backend conventions. Write them where `twenty app apply` does not validate correctness.Always write a test file for every util or function. Whenever you create or modify a file in `src/utils/` (or any other testable function file), you MUST create or update its sibling `__tests__/<name>.spec.ts`. A util or function without a spec file is incomplete.@@ -31,16 +31,16 @@ src/utils/__tests__/map-bar.util.spec.ts## Running Tests-Integration tests build, deploy, install, and uninstall the app on whatever server `TWENTY_API_URL` points to. The scaffold defaults to the dev instance (`http://localhost:2020`), so running them there adds and then removes the app from the workspace you sync to with `yarn twenty apply`. Always run them against the isolated test instance instead — a separate container, database, and port (`2021`) that does not affect your running dev instance:+Integration tests build, deploy, install, and uninstall the app on whatever server `TWENTY_API_URL` points to. The scaffold defaults to the dev instance (`http://localhost:2020`), so running them there adds and then removes the app from the workspace you sync to with `twenty app apply`. Always run them against the isolated test instance instead — a separate container, database, and port (`2021`) that does not affect your running dev instance:```bash-# Start the isolated test instance (once).-yarn twenty docker:start --test+# Start an already provisioned isolated test container.+docker start twenty-app-dev-test# Run integration tests against it.TWENTY_API_URL=http://localhost:2021 yarn test```-The seeded default `TWENTY_API_KEY` works for both instances, so only the URL needs overriding. This mirrors CI, which spawns the same isolated instance via the `spawn-twenty-app-dev-test` action.+Provision the isolated test container before starting it, using the local-server documentation. Set `TWENTY_API_KEY` for that instance; the CLI no longer provisions Docker containers. This mirrors CI, which spawns the same isolated instance via the `spawn-twenty-app-dev-test` action.When the user asks you to run tests, do run them. First start or verify the isolated test instance, then run the test command with `TWENTY_API_URL=http://localhost:2021`. Do not run integration tests against `http://localhost:2020` unless the user explicitly asks to target the dev instance. If only unit tests are requested, use the package's unit-test script and no `TWENTY_API_URL` override is needed.diff --git a/packages/twenty-agent-skills/references/develop-app/workflows.md b/packages/twenty-agent-skills/references/develop-app/workflows.mdindex 90dcbe9e60b..29441264dc0 100644--- a/packages/twenty-agent-skills/references/develop-app/workflows.md+++ b/packages/twenty-agent-skills/references/develop-app/workflows.md@@ -41,7 +41,7 @@ Seeders need workflow settings permissions on the app role. Grant via `defineRol## Invoking Locally```bash-yarn twenty dev:function:exec+twenty app exec```-`yarn twenty apply` skips install hooks. Run it again after rebuilding to verify idempotency.+`twenty app apply` skips install hooks. Run it again after rebuilding to verify idempotency.diff --git a/packages/twenty-agent-skills/references/manage-app/cli-and-sync.md b/packages/twenty-agent-skills/references/manage-app/cli-and-sync.mdindex 4bb66419832..2339f077097 100644--- a/packages/twenty-agent-skills/references/manage-app/cli-and-sync.md+++ b/packages/twenty-agent-skills/references/manage-app/cli-and-sync.md@@ -12,7 +12,7 @@ Before running operational commands, confirm the current directory is a Twenty atest -f package.jsontest -f src/application-config.tssed -n '1,220p' package.json-yarn twenty remote:list+twenty remote list```Treat deploys, uninstalls, production remote changes, and production syncs as externally visible actions. Ask for explicit confirmation before running them when the target is production or user data could be affected.@@ -22,7 +22,7 @@ Treat deploys, uninstalls, production remote changes, and production syncs as exUse these commands to validate an app after changes:```bash-yarn twenty dev:typecheck+twenty app typecheckyarn lint```@@ -30,42 +30,40 @@ If the app is already installed on the active remote, preview and then applythe metadata changes:```bash-yarn twenty plan-yarn twenty apply+twenty app plan+twenty app apply```-`yarn twenty dev:typecheck` checks generated app types and TypeScript compatibility. `yarn lint` checks local lint rules. `yarn twenty plan` previews metadata changes, and `yarn twenty apply` performs a bounded build/sync against the active remote.+`twenty app typecheck` checks generated app types and TypeScript compatibility. `yarn lint` checks local lint rules. `twenty app plan` previews metadata changes, and `twenty app apply` performs a bounded build/sync against the active remote.-`yarn twenty plan` is read-only and requires the app to already be installed-on the active remote. For a first sync, run `yarn twenty apply`; it registers-the app before synchronizing it. `create-twenty-app` normally performs this-initial sync, so a successfully scaffolded app does not need an extra apply.-Use the first-sync path when the scaffold sync failed, or when the app was-created or copied without being installed on this remote.+`twenty app plan` is read-only and requires the app to already be installed+on the active remote. For a first sync, run `twenty app apply --create`; it registers+and installs the app. `twenty app init` only writes the source files, so+installation and authentication are explicit steps.If a validation command fails because of entity definitions, switch to `develop-app` for the fix. If it fails because of remotes, authentication, build tooling, sync, logs, deploys, or CI/CD, stay in `manage-app`.## Remotes-A remote is a Twenty server that the app can sync or deploy to. Credentials are stored locally in `~/.twenty/config.json`.+A remote is a Twenty server that the app can sync or deploy to. Credentials are managed by the standalone CLI. Use `twenty auth login` and `twenty remote list`.Common commands:```bash# Add a remote interactively.-yarn twenty remote:add+twenty auth login# Connect to a local Twenty server.-yarn twenty remote:add --local+twenty auth login --url http://localhost:2020# Add a remote non-interactively.-yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production+printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://your-twenty-server.com --name production# List configured remotes.-yarn twenty remote:list+twenty remote list# Switch the active remote.-yarn twenty remote:use <name>+twenty remote use <name>```When the user says "prod", "production", or "workspace de prod", identify the target remote before syncing or deploying. If it is missing, add it with `--as production` or the user-provided name.@@ -75,17 +73,17 @@ When the user says "prod", "production", or "workspace de prod", identify the taUse the bounded apply command to synchronize app changes with the active remote:```bash-yarn twenty apply+twenty app apply```-Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty apply` each time changes need to be synced.+Do not use bare `twenty app dev` (watch mode). Run `twenty app apply` each time changes need to be synced.Apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.-Use verbose apply for bounded troubleshooting:+Use JSON output to inspect structured errors from a bounded apply:```bash-yarn twenty apply --verbose+twenty app apply --json```## Troubleshooting@@ -104,20 +102,20 @@ Collect the minimum useful context before changing configuration:```bashsed -n '1,220p' package.jsonsed -n '1,220p' src/application-config.ts-yarn twenty remote:list-yarn twenty apply --verbose+twenty remote list+twenty app apply --json```For remote or authentication issues:- Check that the active remote is the intended workspace or server.-- Re-run `yarn twenty remote:add --local` for local app-dev servers.-- Re-run `yarn twenty remote:add --url <url> --as <name>` for remote servers.+- Re-run `twenty auth login --url http://localhost:2020` for local app-dev servers.+- Re-run `twenty auth login --url <url> --name <name>` for remote servers.- Avoid overwriting a production remote until the target URL is confirmed.For sync issues:-- Prefer `yarn twenty apply --verbose` to get a bounded failure.+- Prefer `twenty app apply --json` to get a bounded failure.- Check generated type or schema errors before editing app entities.- If the app depends on a changed data model, use `develop-app` to fix the entity definitions.@@ -126,45 +124,45 @@ For sync issues:Build before deploy when the user asks for release readiness or when debugging packaging issues:```bash-yarn twenty dev:build+twenty app build```Publish an app to npm, or publish privately to a configured Twenty server registry:```bash-yarn twenty app:publish-yarn twenty app:publish --private --remote production-yarn twenty app:install --remote production+twenty app publish+twenty app publish --private --remote production+twenty app install --remote production```-Before deploying an update, check that `package.json` has a strictly higher semver `version` than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with `yarn twenty app:install` when the target workspace should use it.+Before deploying an update, check that `package.json` has a strictly higher semver `version` than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with `twenty app install` when the target workspace should use it.Use function logs when debugging runtime behavior on the connected server:```bash-yarn twenty dev:function:logs-yarn twenty dev:function:logs -n <function-name>+twenty app logs+twenty app logs --name <function-name>```Run a logic function manually when testing behavior without its trigger:```bash-yarn twenty dev:function:exec -n <function-name>-yarn twenty dev:function:exec -n <function-name> -p '{"key":"value"}'+twenty app exec --name <function-name>+twenty app exec --name <function-name> --payload '{"key":"value"}'```Uninstall only after confirmation:```bash-yarn twenty app:uninstall-yarn twenty app:uninstall --yes+twenty app uninstall+twenty app uninstall --yes```-Integration tests install and uninstall the app on their target server, so run them against the isolated test instance (`yarn twenty docker:start --test`, port `2021`) rather than the dev instance — see `../develop-app/tests.md`.+Integration tests install and uninstall the app on their target server, so run them against the isolated test instance (`docker start twenty-app-dev-test`, port `2021`) rather than the dev instance — see `../develop-app/tests.md`.## CI/CD-Apps generated with `create-twenty-app` can use GitHub Actions for CI and CD. For deployment automation, check the app's `.github/workflows/` files and configure:+Apps generated with `twenty app init` can use GitHub Actions for CI and CD. For deployment automation, check the app's `.github/workflows/` files and configure:- `TWENTY_DEPLOY_URL`- `TWENTY_DEPLOY_API_KEY`diff --git a/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md b/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.mdindex 9ee05051bbb..3c80cd30f7b 100644--- a/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md+++ b/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md@@ -155,7 +155,7 @@ Logo guidance:Screenshot guidance:-- Capture real app surfaces after `yarn twenty apply` or watch-mode sync.+- Capture real app surfaces after `twenty app apply` or watch-mode sync.- Prefer the most useful user paths: app listing/about page, object index view, record page layout, front component surface, connection settings, or AI skill/agent behavior.- Use seeded or synthetic data only.- Hide browser chrome unless it helps explain setup.@@ -195,8 +195,8 @@ If the app requires a specific Twenty server version, set `engines.twenty` in `pBefore considering README and visuals done:```bash-yarn twenty apply-yarn twenty dev:build+twenty app apply+twenty app build```Then check:diff --git a/packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.js b/packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.jsindex 6ba8aa3ad0a..b69f28f78eb 100644--- a/packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.js+++ b/packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.js@@ -19,7 +19,11 @@ const PLUGIN_ROOT = path.resolve(const PLUGIN_JSON_PATH = path.join(PLUGIN_ROOT, '.codex-plugin', 'plugin.json');const PACKAGE_JSON_PATH = path.join(PLUGIN_ROOT, 'package.json');const MCP_JSON_PATH = path.join(PLUGIN_ROOT, '.mcp.json');-const MARKETPLACE_TEMPLATE_PATH = path.join(PLUGIN_ROOT, 'templates', 'marketplace.example.json');+const MARKETPLACE_TEMPLATE_PATH = path.join(+ PLUGIN_ROOT,+ 'templates',+ 'marketplace.example.json',+);const collectFailures = (assertion) => {const failures = [];@@ -65,7 +69,10 @@ test('assertJsonMetadata passes on current state', () => {});test('assertNoBundledMcpConfig passes on current state', () => {- assert.deepStrictEqual(collectFailures(metadata.assertNoBundledMcpConfig), []);+ assert.deepStrictEqual(+ collectFailures(metadata.assertNoBundledMcpConfig),+ [],+ );});test('assertInterfaceFields passes on current state', () => {@@ -73,7 +80,10 @@ test('assertInterfaceFields passes on current state', () => {});test('assertMarketplaceTemplate passes on current state', () => {- assert.deepStrictEqual(collectFailures(metadata.assertMarketplaceTemplate), []);+ assert.deepStrictEqual(+ collectFailures(metadata.assertMarketplaceTemplate),+ [],+ );});test('assertAssets passes on current state', () => {@@ -89,7 +99,10 @@ test('assertSkillTriggerPhrases passes on current state', () => {});test('assertNoLegacySkillReferences passes on current state', () => {- assert.deepStrictEqual(collectFailures(skills.assertNoLegacySkillReferences), []);+ assert.deepStrictEqual(+ collectFailures(skills.assertNoLegacySkillReferences),+ [],+ );});test('assertReferences passes on current state', () => {@@ -101,11 +114,17 @@ test('assertHowAppsWork passes on current state', () => {});test('assertTwentyMcpFormattingContract passes on current state', () => {- assert.deepStrictEqual(collectFailures(crossDocContracts.assertTwentyMcpFormattingContract), []);+ assert.deepStrictEqual(+ collectFailures(crossDocContracts.assertTwentyMcpFormattingContract),+ [],+ );});test('assertFrontComponentGuidance passes on current state', () => {- assert.deepStrictEqual(collectFailures(crossDocContracts.assertFrontComponentGuidance), []);+ assert.deepStrictEqual(+ collectFailures(crossDocContracts.assertFrontComponentGuidance),+ [],+ );});test('assertFrontComponentGuidance catches independent UI version guidance', () => {@@ -116,19 +135,27 @@ test('assertFrontComponentGuidance catches independent UI version guidance', ()withFileMutation(frontComponentsPath,- (contents) => contents.replace(- 'at the same version as `twenty-sdk` and `twenty-client-sdk`',- 'at an independent version',- ),+ (contents) =>+ contents.replace(+ 'at the same version as `twenty-sdk` and `twenty-client-sdk`',+ 'at an independent version',+ ),() => {- const failures = collectFailures(crossDocContracts.assertFrontComponentGuidance);- assert.ok(failures.some((failure) => failure.includes('same version as')));+ const failures = collectFailures(+ crossDocContracts.assertFrontComponentGuidance,+ );+ assert.ok(+ failures.some((failure) => failure.includes('same version as')),+ );},);});test('assertCliGuidanceSplit passes on current state', () => {- assert.deepStrictEqual(collectFailures(crossDocContracts.assertCliGuidanceSplit), []);+ assert.deepStrictEqual(+ collectFailures(crossDocContracts.assertCliGuidanceSplit),+ [],+ );});test('assertCliGuidanceSplit catches deprecated dev --once guidance', () => {@@ -141,9 +168,12 @@ test('assertCliGuidanceSplit catches deprecated dev --once guidance', () => {withFileMutation(cliAndSyncPath,- (contents) => contents.replace('yarn twenty apply', 'yarn twenty dev --once'),+ (contents) =>+ contents.replace('twenty app apply', 'yarn twenty dev --once'),() => {- const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);+ const failures = collectFailures(+ crossDocContracts.assertCliGuidanceSplit,+ );assert.ok(failures.some((failure) => failure.includes('yarn twenty dev --once')),@@ -164,7 +194,9 @@ test('assertCliGuidanceSplit catches deprecated guidance outside the CLI referenmanageSkillPath,(contents) => `${contents}\nRun yarn twenty dev --once after editing.\n`,() => {- const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);+ const failures = collectFailures(+ crossDocContracts.assertCliGuidanceSplit,+ );assert.ok(failures.some(@@ -189,7 +221,9 @@ test('assertCliGuidanceSplit catches stale one-shot sync terminology', () => {standalonePagesPath,(contents) => `${contents}\nUse one-shot sync for verification.\n`,() => {- const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);+ const failures = collectFailures(+ crossDocContracts.assertCliGuidanceSplit,+ );assert.ok(failures.some(@@ -203,7 +237,10 @@ test('assertCliGuidanceSplit catches stale one-shot sync terminology', () => {});test('assertTestingGuidance passes on current state', () => {- assert.deepStrictEqual(collectFailures(crossDocContracts.assertTestingGuidance), []);+ assert.deepStrictEqual(+ collectFailures(crossDocContracts.assertTestingGuidance),+ [],+ );});test('assertSetupHelper passes on current state', () => {@@ -211,231 +248,418 @@ test('assertSetupHelper passes on current state', () => {});test('assertJsonMetadata catches version mismatch between package.json and plugin.json', () => {- withJsonMutation(PACKAGE_JSON_PATH, (pkg) => { pkg.version = '99.99.99'; }, () => {- const failures = collectFailures(metadata.assertJsonMetadata);- assert.ok(- failures.some((f) => f.includes('version must match')),- `expected version-mismatch failure, got: ${failures.join('; ')}`,- );- });+ withJsonMutation(+ PACKAGE_JSON_PATH,+ (packageJson) => {+ packageJson.version = '99.99.99';+ },+ () => {+ const failures = collectFailures(metadata.assertJsonMetadata);+ assert.ok(+ failures.some((f) => f.includes('version must match')),+ `expected version-mismatch failure, got: ${failures.join('; ')}`,+ );+ },+ );});test('assertJsonMetadata catches missing .mcp.json from package.json files', () => {- withJsonMutation(PACKAGE_JSON_PATH, (pkg) => {- pkg.files = pkg.files.filter((f) => f !== '.mcp.json');- }, () => {- const failures = collectFailures(metadata.assertJsonMetadata);- assert.ok(failures.some((f) => f.includes('.mcp.json')));- });+ withJsonMutation(+ PACKAGE_JSON_PATH,+ (packageJson) => {+ packageJson.files = packageJson.files.filter((f) => f !== '.mcp.json');+ },+ () => {+ const failures = collectFailures(metadata.assertJsonMetadata);+ assert.ok(failures.some((f) => f.includes('.mcp.json')));+ },+ );});test('assertJsonMetadata catches non-canonical MCP server', () => {- withJsonMutation(MCP_JSON_PATH, (mcp) => {- mcp.mcpServers['rogue-server'] = { url: 'https://example.com/mcp' };- }, () => {- const failures = collectFailures(metadata.assertJsonMetadata);- assert.ok(failures.some((f) => f.includes('twenty-docs')));- });+ withJsonMutation(+ MCP_JSON_PATH,+ (mcp) => {+ mcp.mcpServers['rogue-server'] = { url: 'https://example.com/mcp' };+ },+ () => {+ const failures = collectFailures(metadata.assertJsonMetadata);+ assert.ok(failures.some((f) => f.includes('twenty-docs')));+ },+ );});test('assertNoBundledMcpConfig catches a bundled .app.json', () => {const stub = path.join(PLUGIN_ROOT, '.app.json');withExtraFile(stub, '{}', () => {const failures = collectFailures(metadata.assertNoBundledMcpConfig);- assert.ok(failures.some((f) => f.includes('app declarations must not be shipped')));+ assert.ok(+ failures.some((f) => f.includes('app declarations must not be shipped')),+ );});});test('assertNoBundledMcpConfig catches a non-placeholder URL', () => {const stub = path.join(PLUGIN_ROOT, 'scratch-url-check.md');- withExtraFile(stub, 'see https://internal.private-domain.test/secret for details', () => {- const failures = collectFailures(metadata.assertNoBundledMcpConfig);- assert.ok(failures.some((f) => f.includes('non-placeholder URL')));- });+ withExtraFile(+ stub,+ 'see https://internal.private-domain.test/secret for details',+ () => {+ const failures = collectFailures(metadata.assertNoBundledMcpConfig);+ assert.ok(failures.some((f) => f.includes('non-placeholder URL')));+ },+ );});test('assertNoBundledMcpConfig catches a bearer token', () => {const stub = path.join(PLUGIN_ROOT, 'scratch-bearer.md');- withExtraFile(stub, 'Authorization: Bearer abc123def456ghi789jkl012mno', () => {- const failures = collectFailures(metadata.assertNoBundledMcpConfig);- assert.ok(failures.some((f) => f.includes('bearer token')));- });+ withExtraFile(+ stub,+ 'Authorization: Bearer abc123def456ghi789jkl012mno',+ () => {+ const failures = collectFailures(metadata.assertNoBundledMcpConfig);+ assert.ok(failures.some((f) => f.includes('bearer token')));+ },+ );});test('source scans ignore generated distribution files', () => {const distributionRoot = path.join(PLUGIN_ROOT, 'dist');fs.mkdirSync(distributionRoot, { recursive: true });- const fixtureRoot = fs.mkdtempSync(path.join(distributionRoot, 'source-validation-'));+ const fixtureRoot = fs.mkdtempSync(+ path.join(distributionRoot, 'source-validation-'),+ );try {fs.writeFileSync(path.join(fixtureRoot, '.mcp.json'), '{}');- fs.writeFileSync(path.join(fixtureRoot, 'SKILL.md'), 'name: create-an-app\n');+ fs.writeFileSync(+ path.join(fixtureRoot, 'SKILL.md'),+ 'name: create-an-app\n',+ );- assert.deepStrictEqual(collectFailures(metadata.assertNoBundledMcpConfig), []);- assert.deepStrictEqual(collectFailures(skills.assertNoLegacySkillReferences), []);+ assert.deepStrictEqual(+ collectFailures(metadata.assertNoBundledMcpConfig),+ [],+ );+ assert.deepStrictEqual(+ collectFailures(skills.assertNoLegacySkillReferences),+ [],+ );} finally {fs.rmSync(fixtureRoot, { recursive: true, force: true });}});test('assertInterfaceFields catches invalid brandColor', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.brandColor = 'red'; }, () => {- const failures = collectFailures(metadata.assertInterfaceFields);- assert.ok(failures.some((f) => f.includes('brandColor must match')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.brandColor = 'red';+ },+ () => {+ const failures = collectFailures(metadata.assertInterfaceFields);+ assert.ok(failures.some((f) => f.includes('brandColor must match')));+ },+ );});test('assertInterfaceFields catches too-long shortDescription', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.shortDescription = 'x'.repeat(100); }, () => {- const failures = collectFailures(metadata.assertInterfaceFields);- assert.ok(failures.some((f) => f.includes('shortDescription must be 64')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.shortDescription = 'x'.repeat(100);+ },+ () => {+ const failures = collectFailures(metadata.assertInterfaceFields);+ assert.ok(+ failures.some((f) => f.includes('shortDescription must be 64')),+ );+ },+ );});test('assertInterfaceFields catches unknown category', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.category = 'Photography'; }, () => {- const failures = collectFailures(metadata.assertInterfaceFields);- assert.ok(failures.some((f) => f.includes('category must be one of')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.category = 'Photography';+ },+ () => {+ const failures = collectFailures(metadata.assertInterfaceFields);+ assert.ok(failures.some((f) => f.includes('category must be one of')));+ },+ );});test('assertInterfaceFields catches invalid capability', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.capabilities = ['Magic']; }, () => {- const failures = collectFailures(metadata.assertInterfaceFields);- assert.ok(failures.some((f) => f.includes('capabilities contains invalid value')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.capabilities = ['Magic'];+ },+ () => {+ const failures = collectFailures(metadata.assertInterfaceFields);+ assert.ok(+ failures.some((f) => f.includes('capabilities contains invalid value')),+ );+ },+ );});test('assertInterfaceFields catches empty defaultPrompt', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.defaultPrompt = []; }, () => {- const failures = collectFailures(metadata.assertInterfaceFields);- assert.ok(failures.some((f) => f.includes('defaultPrompt')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.defaultPrompt = [];+ },+ () => {+ const failures = collectFailures(metadata.assertInterfaceFields);+ assert.ok(failures.some((f) => f.includes('defaultPrompt')));+ },+ );});test('assertAssets catches a missing screenshot reference', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => {- j.interface.screenshots = ['./assets/screenshots/nonexistent.png'];- }, () => {- const failures = collectFailures(assets.assertAssets);- assert.ok(failures.some((f) => f.includes('screenshots entry is missing')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.screenshots = [+ './assets/screenshots/nonexistent.png',+ ];+ },+ () => {+ const failures = collectFailures(assets.assertAssets);+ assert.ok(+ failures.some((f) => f.includes('screenshots entry is missing')),+ );+ },+ );});test('assertAssets catches a non-PNG logo', () => {- withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.logo = './assets/twenty-logo.svg'; }, () => {- const failures = collectFailures(assets.assertAssets);- assert.ok(failures.some((f) => f.includes('logo must be a PNG')));- });+ withJsonMutation(+ PLUGIN_JSON_PATH,+ (pluginJson) => {+ pluginJson.interface.logo = './assets/twenty-logo.svg';+ },+ () => {+ const failures = collectFailures(assets.assertAssets);+ assert.ok(failures.some((f) => f.includes('logo must be a PNG')));+ },+ );});test('assertMarketplaceTemplate requires marketplace identity', () => {- withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {- delete template.name;- delete template.interface;- }, () => {- const failures = collectFailures(metadata.assertMarketplaceTemplate);- assert.ok(failures.some((failure) => failure.includes('name must be a non-empty string')));- assert.ok(failures.some((failure) => failure.includes('interface.displayName must be a non-empty string')));- });+ withJsonMutation(+ MARKETPLACE_TEMPLATE_PATH,+ (template) => {+ template.name = undefined;+ template.interface = undefined;+ },+ () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(+ failures.some((failure) =>+ failure.includes('name must be a non-empty string'),+ ),+ );+ assert.ok(+ failures.some((failure) =>+ failure.includes('interface.displayName must be a non-empty string'),+ ),+ );+ },+ );});test('assertMarketplaceTemplate catches the legacy source descriptor', () => {- withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {- template.plugins[0].source = {- type: 'local',- path: './packages/twenty-agent-skills/dist',- };- }, () => {- const failures = collectFailures(metadata.assertMarketplaceTemplate);- assert.ok(failures.some((failure) => failure.includes('source.source must be local')));- });+ withJsonMutation(+ MARKETPLACE_TEMPLATE_PATH,+ (template) => {+ template.plugins[0].source = {+ type: 'local',+ path: './packages/twenty-agent-skills/dist',+ };+ },+ () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(+ failures.some((failure) =>+ failure.includes('source.source must be local'),+ ),+ );+ },+ );});-for (const [field, value] of [['installation', 'manual'], ['authentication', 'user-local']]) {+for (const [field, value] of [+ ['installation', 'manual'],+ ['authentication', 'user-local'],+]) {test(`assertMarketplaceTemplate catches legacy ${field} policy`, () => {- withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {- template.plugins[0].policy[field] = value;- }, () => {- const failures = collectFailures(metadata.assertMarketplaceTemplate);- assert.ok(failures.some((failure) => failure.includes(`policy.${field} must be`)));- });+ withJsonMutation(+ MARKETPLACE_TEMPLATE_PATH,+ (template) => {+ template.plugins[0].policy[field] = value;+ },+ () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(+ failures.some((failure) =>+ failure.includes(`policy.${field} must be`),+ ),+ );+ },+ );});}test('assertMarketplaceTemplate requires the installable distribution path', () => {- withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {- template.plugins[0].source.path = './packages/twenty-agent-skills';- }, () => {- const failures = collectFailures(metadata.assertMarketplaceTemplate);- assert.ok(failures.some((failure) => failure.includes('source.path must be ./packages/twenty-agent-skills/dist')));- });+ withJsonMutation(+ MARKETPLACE_TEMPLATE_PATH,+ (template) => {+ template.plugins[0].source.path = './packages/twenty-agent-skills';+ },+ () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(+ failures.some((failure) =>+ failure.includes(+ 'source.path must be ./packages/twenty-agent-skills/dist',+ ),+ ),+ );+ },+ );});test('assertSkillTriggerPhrases catches a SKILL.md missing the When To Use section', () => {const skillPath = path.join(PLUGIN_ROOT, 'skills', 'create-app', 'SKILL.md');- withFileMutation(skillPath, (original) => original.replace(/^#+\s+When To Use[\s\S]*?(?=\n#\s)/m, ''), () => {- const failures = collectFailures(skills.assertSkillTriggerPhrases);- assert.ok(failures.some((f) => f.includes('create-app') && f.includes('When To Use')));- });+ withFileMutation(+ skillPath,+ (original) => original.replace(/^#+\s+When To Use[\s\S]*?(?=\n#\s)/m, ''),+ () => {+ const failures = collectFailures(skills.assertSkillTriggerPhrases);+ assert.ok(+ failures.some(+ (f) => f.includes('create-app') && f.includes('When To Use'),+ ),+ );+ },+ );});test('assertTestingGuidance catches missing manage-app test target instructions', () => {const skillPath = path.join(PLUGIN_ROOT, 'skills', 'manage-app', 'SKILL.md');- withFileMutation(skillPath, (original) => original.replace('TWENTY_API_URL=http://localhost:2021 yarn test', 'yarn test'), () => {- const failures = collectFailures(crossDocContracts.assertTestingGuidance);- assert.ok(- failures.some((f) => f.includes('manage-app/SKILL.md') && f.includes('TWENTY_API_URL')),- `expected manage-app test target failure, got: ${failures.join('; ')}`,- );- });+ withFileMutation(+ skillPath,+ (original) =>+ original.replace(+ 'TWENTY_API_URL=http://localhost:2021 yarn test',+ 'yarn test',+ ),+ () => {+ const failures = collectFailures(crossDocContracts.assertTestingGuidance);+ assert.ok(+ failures.some(+ (f) =>+ f.includes('manage-app/SKILL.md') && f.includes('TWENTY_API_URL'),+ ),+ `expected manage-app test target failure, got: ${failures.join('; ')}`,+ );+ },+ );});test('assertOperatingRulesSingleSource passes on current state', () => {- assert.deepStrictEqual(collectFailures(crossDocContracts.assertOperatingRulesSingleSource), []);+ assert.deepStrictEqual(+ collectFailures(crossDocContracts.assertOperatingRulesSingleSource),+ [],+ );});test('assertOperatingRulesSingleSource catches AGENTS.md restating a rule', () => {const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');- withFileMutation(agentsPath, (original) => `${original}\n1. **Confirm destructive operations.** Restated.\n`, () => {- const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);- assert.ok(- failures.some((f) => f.includes('AGENTS.md') && f.includes('restates an operating rule')),- `expected a restated-rule failure, got: ${failures.join('; ')}`,- );- });+ withFileMutation(+ agentsPath,+ (original) =>+ `${original}\n1. **Confirm destructive operations.** Restated.\n`,+ () => {+ const failures = collectFailures(+ crossDocContracts.assertOperatingRulesSingleSource,+ );+ assert.ok(+ failures.some(+ (f) =>+ f.includes('AGENTS.md') && f.includes('restates an operating rule'),+ ),+ `expected a restated-rule failure, got: ${failures.join('; ')}`,+ );+ },+ );});test('assertOperatingRulesSingleSource catches AGENTS.md losing the pointer', () => {const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');- withFileMutation(agentsPath, (original) => original.replaceAll('references/concepts/operating-rules.md', 'nowhere.md'), () => {- const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);- assert.ok(- failures.some((f) => f.includes('AGENTS.md must point at')),- `expected a missing-pointer failure, got: ${failures.join('; ')}`,- );- });+ withFileMutation(+ agentsPath,+ (original) =>+ original.replaceAll(+ 'references/concepts/operating-rules.md',+ 'nowhere.md',+ ),+ () => {+ const failures = collectFailures(+ crossDocContracts.assertOperatingRulesSingleSource,+ );+ assert.ok(+ failures.some((f) => f.includes('AGENTS.md must point at')),+ `expected a missing-pointer failure, got: ${failures.join('; ')}`,+ );+ },+ );});test('assertHowAppsWork catches a skill that does not reference operating-rules.md', () => {const skillPath = path.join(PLUGIN_ROOT, 'skills', 'develop-app', 'SKILL.md');- withFileMutation(skillPath, (original) => original.replace('../../references/concepts/operating-rules.md', 'nowhere.md'), () => {- const failures = collectFailures(references.assertHowAppsWork);- assert.ok(- failures.some((f) => f.includes('develop-app/SKILL.md') && f.includes('operating-rules.md')),- `expected an operating-rules reference failure, got: ${failures.join('; ')}`,- );- });+ withFileMutation(+ skillPath,+ (original) =>+ original.replace(+ '../../references/concepts/operating-rules.md',+ 'nowhere.md',+ ),+ () => {+ const failures = collectFailures(references.assertHowAppsWork);+ assert.ok(+ failures.some(+ (f) =>+ f.includes('develop-app/SKILL.md') &&+ f.includes('operating-rules.md'),+ ),+ `expected an operating-rules reference failure, got: ${failures.join('; ')}`,+ );+ },+ );});test('assertOperatingRulesSingleSource catches prose copied from the rules file', () => {const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');- const copiedSentence = 'Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.';- withFileMutation(agentsPath, (original) => `${original}\n${copiedSentence}\n`, () => {- const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);- assert.ok(- failures.some((f) => f.includes('AGENTS.md') && f.includes('copies a sentence')),- `expected a copied-prose failure, got: ${failures.join('; ')}`,- );- });+ const copiedSentence =+ 'Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.';+ withFileMutation(+ agentsPath,+ (original) => `${original}\n${copiedSentence}\n`,+ () => {+ const failures = collectFailures(+ crossDocContracts.assertOperatingRulesSingleSource,+ );+ assert.ok(+ failures.some(+ (f) => f.includes('AGENTS.md') && f.includes('copies a sentence'),+ ),+ `expected a copied-prose failure, got: ${failures.join('; ')}`,+ );+ },+ );});diff --git a/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.jsindex 46356936c6e..d6b0b4b393d 100644--- a/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js+++ b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js@@ -5,7 +5,10 @@ import { PLUGIN_ROOT, listFiles, readText } from './lib.js';const assertTwentyMcpFormattingContract = (fail) => {const skillPath = path.join(PLUGIN_ROOT, 'skills/use-twenty-mcp/SKILL.md');- const resultFormattingPath = path.join(PLUGIN_ROOT, 'references/use-twenty-mcp/result-formatting.md');+ const resultFormattingPath = path.join(+ PLUGIN_ROOT,+ 'references/use-twenty-mcp/result-formatting.md',+ );const skill = readText(skillPath);const formatting = readText(resultFormattingPath);@@ -19,7 +22,9 @@ const assertTwentyMcpFormattingContract = (fail) => {for (const fragment of requiredSkillFragments) {if (!skill.includes(fragment)) {- fail(`use-twenty-mcp/SKILL.md is missing formatting contract fragment: ${fragment}`);+ fail(+ `use-twenty-mcp/SKILL.md is missing formatting contract fragment: ${fragment}`,+ );}}@@ -33,18 +38,35 @@ const assertTwentyMcpFormattingContract = (fail) => {for (const fragment of requiredFormattingFragments) {if (!formatting.includes(fragment)) {- fail(`result-formatting.md is missing record-link guidance fragment: ${fragment}`);+ fail(+ `result-formatting.md is missing record-link guidance fragment: ${fragment}`,+ );}}};const assertFrontComponentGuidance = (fail) => {- const developSkillPath = path.join(PLUGIN_ROOT, 'skills/develop-app/SKILL.md');+ const developSkillPath = path.join(+ PLUGIN_ROOT,+ 'skills/develop-app/SKILL.md',+ );const layoutPath = path.join(PLUGIN_ROOT, 'references/develop-app/layout.md');- const frontComponentsPath = path.join(PLUGIN_ROOT, 'references/develop-app/front-components.md');- const standalonePagesPath = path.join(PLUGIN_ROOT, 'references/develop-app/standalone-pages.md');- const appStructurePath = path.join(PLUGIN_ROOT, 'references/develop-app/app-structure.md');- const frontComponentUiPath = path.join(PLUGIN_ROOT, 'references/design/front-component-ui.md');+ const frontComponentsPath = path.join(+ PLUGIN_ROOT,+ 'references/develop-app/front-components.md',+ );+ const standalonePagesPath = path.join(+ PLUGIN_ROOT,+ 'references/develop-app/standalone-pages.md',+ );+ const appStructurePath = path.join(+ PLUGIN_ROOT,+ 'references/develop-app/app-structure.md',+ );+ const frontComponentUiPath = path.join(+ PLUGIN_ROOT,+ 'references/design/front-component-ui.md',+ );const developSkill = readText(developSkillPath);const layout = readText(layoutPath);const frontComponents = readText(frontComponentsPath);@@ -61,7 +83,9 @@ const assertFrontComponentGuidance = (fail) => {for (const fragment of requiredDevelopSkillFragments) {if (!developSkill.includes(fragment)) {- fail(`develop-app/SKILL.md is missing front component guidance: ${fragment}`);+ fail(+ `develop-app/SKILL.md is missing front component guidance: ${fragment}`,+ );}}@@ -111,24 +135,28 @@ const assertFrontComponentGuidance = (fail) => {'owns internal scrolling','Full-Page Layout Guidance','black screen',- 'yarn twenty apply',+ 'twenty app apply',];for (const fragment of requiredStandalonePageFragments) {if (!standalonePages.includes(fragment)) {- fail(`standalone-pages.md is missing standalone page guidance: ${fragment}`);+ fail(+ `standalone-pages.md is missing standalone page guidance: ${fragment}`,+ );}}const requiredAppStructureFragments = [- 'yarn twenty dev:typecheck',+ 'twenty app typecheck','yarn lint',- 'yarn twenty apply',+ 'twenty app apply',];for (const fragment of requiredAppStructureFragments) {if (!appStructure.includes(fragment)) {- fail(`app-structure.md is missing validation checklist command: ${fragment}`);+ fail(+ `app-structure.md is missing validation checklist command: ${fragment}`,+ );}}@@ -146,7 +174,9 @@ const assertFrontComponentGuidance = (fail) => {for (const fragment of requiredUiDesignFragments) {if (!frontComponentUi.includes(fragment)) {- fail(`front-component-ui.md is missing design-only guidance: ${fragment}`);+ fail(+ `front-component-ui.md is missing design-only guidance: ${fragment}`,+ );}}@@ -159,16 +189,27 @@ const assertFrontComponentGuidance = (fail) => {for (const fragment of forbiddenUiFragments) {if (frontComponentUi.includes(fragment)) {- fail(`front-component-ui.md should stay design-only and not include: ${fragment}`);+ fail(+ `front-component-ui.md should stay design-only and not include: ${fragment}`,+ );}}};const assertCliGuidanceSplit = (fail) => {- const developSkillPath = path.join(PLUGIN_ROOT, 'skills/develop-app/SKILL.md');+ const developSkillPath = path.join(+ PLUGIN_ROOT,+ 'skills/develop-app/SKILL.md',+ );const manageSkillPath = path.join(PLUGIN_ROOT, 'skills/manage-app/SKILL.md');- const appStructurePath = path.join(PLUGIN_ROOT, 'references/develop-app/app-structure.md');- const cliAndSyncPath = path.join(PLUGIN_ROOT, 'references/manage-app/cli-and-sync.md');+ const appStructurePath = path.join(+ PLUGIN_ROOT,+ 'references/develop-app/app-structure.md',+ );+ const cliAndSyncPath = path.join(+ PLUGIN_ROOT,+ 'references/manage-app/cli-and-sync.md',+ );const developSkill = readText(developSkillPath);const manageSkill = readText(manageSkillPath);const appStructure = readText(appStructurePath);@@ -176,8 +217,8 @@ const assertCliGuidanceSplit = (fail) => {const requiredDevelopFragments = ['references/develop-app/app-structure.md',- 'yarn twenty dev:add',- 'yarn twenty apply',+ 'twenty app add',+ 'twenty app apply','switch to `manage-app`',];@@ -195,7 +236,9 @@ const assertCliGuidanceSplit = (fail) => {for (const fragment of requiredManageFragments) {if (!manageSkill.includes(fragment)) {- fail(`manage-app/SKILL.md is missing CLI reference guidance: ${fragment}`);+ fail(+ `manage-app/SKILL.md is missing CLI reference guidance: ${fragment}`,+ );}}@@ -205,14 +248,16 @@ const assertCliGuidanceSplit = (fail) => {'## Entity Creation','## Validation Checklist','run lint and typecheck once at the end (not after each individual edit)',- 'yarn twenty dev:typecheck',+ 'twenty app typecheck','yarn lint',- 'yarn twenty apply',+ 'twenty app apply',];for (const fragment of requiredAppStructureFragments) {if (!appStructure.includes(fragment)) {- fail(`app-structure.md is missing develop-app structure guidance: ${fragment}`);+ fail(+ `app-structure.md is missing develop-app structure guidance: ${fragment}`,+ );}}@@ -223,57 +268,63 @@ const assertCliGuidanceSplit = (fail) => {'Use one-shot mode for agents','yarn twenty dev --once','yarn twenty dev --once --verbose',- 'yarn twenty remote:list',- 'Do not run `yarn twenty dev:typecheck`',+ 'twenty remote list',+ 'Do not run `twenty app typecheck`','run outside the sandbox','incompatible Node and Yarn',];for (const fragment of forbiddenAppStructureFragments) {if (appStructure.includes(fragment)) {- fail(`app-structure.md should not own CLI semantics or forbid post-edit validation: ${fragment}`);+ fail(+ `app-structure.md should not own CLI semantics or forbid post-edit validation: ${fragment}`,+ );}}const requiredDevelopValidationFragments = ['run lint and typecheck once at the end (not after each individual edit)',- 'yarn twenty dev:typecheck',+ 'twenty app typecheck','yarn lint',];for (const fragment of requiredDevelopValidationFragments) {if (!developSkill.includes(fragment)) {- fail(`develop-app/SKILL.md is missing post-edit validation guidance: ${fragment}`);+ fail(+ `develop-app/SKILL.md is missing post-edit validation guidance: ${fragment}`,+ );}}const forbiddenDevelopFragments = [- 'Do not run `yarn twenty dev:typecheck`',+ 'Do not run `twenty app typecheck`','debug the toolchain','run outside the sandbox',];for (const fragment of forbiddenDevelopFragments) {if (developSkill.includes(fragment)) {- fail(`develop-app/SKILL.md should not forbid post-edit validation or warn about the sandbox: ${fragment}`);+ fail(+ `develop-app/SKILL.md should not forbid post-edit validation or warn about the sandbox: ${fragment}`,+ );}}const requiredCliFragments = ['# CLI And Sync',- 'yarn twenty dev:typecheck',+ 'twenty app typecheck','yarn lint',- 'yarn twenty plan',- 'yarn twenty apply',- '`yarn twenty plan` is read-only and requires the app to already be installed',- 'For a first sync, run `yarn twenty apply`',+ 'twenty app plan',+ 'twenty app apply',+ '`twenty app plan` is read-only and requires the app to already be installed',+ 'For a first sync, run `twenty app apply --create`','Use the bounded apply command to synchronize app changes with the active remote',- 'Do not use bare `yarn twenty dev` (watch mode)',- 'yarn twenty apply --verbose',- 'yarn twenty remote:list',- 'yarn twenty dev:build',- 'yarn twenty app:publish',- 'yarn twenty dev:function:logs',+ 'Do not use bare `twenty app dev` (watch mode)',+ 'twenty app apply --json',+ 'twenty remote list',+ 'twenty app build',+ 'twenty app publish',+ 'twenty app logs',];for (const fragment of requiredCliFragments) {@@ -291,7 +342,9 @@ const assertCliGuidanceSplit = (fail) => {for (const fragment of forbiddenCliFragments) {if (cliAndSync.includes(fragment)) {- fail(`cli-and-sync.md should not warn about the sandbox or reference the removed command-execution.md: ${fragment}`);+ fail(+ `cli-and-sync.md should not warn about the sandbox or reference the removed command-execution.md: ${fragment}`,+ );}}@@ -324,8 +377,14 @@ const assertCliGuidanceSplit = (fail) => {const assertTestingGuidance = (fail) => {const manageSkillPath = path.join(PLUGIN_ROOT, 'skills/manage-app/SKILL.md');const testsPath = path.join(PLUGIN_ROOT, 'references/develop-app/tests.md');- const cliAndSyncPath = path.join(PLUGIN_ROOT, 'references/manage-app/cli-and-sync.md');- const operatingRulesPath = path.join(PLUGIN_ROOT, 'references/concepts/operating-rules.md');+ const cliAndSyncPath = path.join(+ PLUGIN_ROOT,+ 'references/manage-app/cli-and-sync.md',+ );+ const operatingRulesPath = path.join(+ PLUGIN_ROOT,+ 'references/concepts/operating-rules.md',+ );const manageSkill = readText(manageSkillPath);const tests = readText(testsPath);const cliAndSync = readText(cliAndSyncPath);@@ -334,14 +393,16 @@ const assertTestingGuidance = (fail) => {const requiredManageFragments = ['run tests for my Twenty app','references/develop-app/tests.md',- 'yarn twenty docker:start --test',+ 'docker start twenty-app-dev-test','TWENTY_API_URL=http://localhost:2021 yarn test','Do not run integration tests against the dev instance on `http://localhost:2020`',];for (const fragment of requiredManageFragments) {if (!manageSkill.includes(fragment)) {- fail(`manage-app/SKILL.md is missing test execution guidance: ${fragment}`);+ fail(+ `manage-app/SKILL.md is missing test execution guidance: ${fragment}`,+ );}}@@ -354,20 +415,24 @@ const assertTestingGuidance = (fail) => {for (const fragment of requiredSharedFragments) {if (!tests.includes(fragment)) {- fail(`tests.md is missing isolated integration-test guidance: ${fragment}`);+ fail(+ `tests.md is missing isolated integration-test guidance: ${fragment}`,+ );}}const requiredCliFragments = ['Integration tests install and uninstall the app on their target server',- 'yarn twenty docker:start --test',+ 'docker start twenty-app-dev-test','port `2021`','../develop-app/tests.md',];for (const fragment of requiredCliFragments) {if (!cliAndSync.includes(fragment)) {- fail(`cli-and-sync.md is missing integration-test target guidance: ${fragment}`);+ fail(+ `cli-and-sync.md is missing integration-test target guidance: ${fragment}`,+ );}}@@ -378,7 +443,9 @@ const assertTestingGuidance = (fail) => {for (const fragment of requiredOperatingRulesFragments) {if (!operatingRules.includes(fragment)) {- fail(`operating-rules.md is missing durable test target guidance: ${fragment}`);+ fail(+ `operating-rules.md is missing durable test target guidance: ${fragment}`,+ );}}};@@ -395,10 +462,15 @@ const OPERATING_RULE_HEADLINES = [// Every entry point links to the operating rules to keep authored guidance// from drifting between skills and the Codex wrapper.const assertOperatingRulesSingleSource = (fail) => {- const operatingRulesPath = path.join(PLUGIN_ROOT, 'references/concepts/operating-rules.md');+ const operatingRulesPath = path.join(+ PLUGIN_ROOT,+ 'references/concepts/operating-rules.md',+ );if (!fs.existsSync(operatingRulesPath)) {- fail('required reference is missing: references/concepts/operating-rules.md');+ fail(+ 'required reference is missing: references/concepts/operating-rules.md',+ );return;}@@ -412,7 +484,9 @@ const assertOperatingRulesSingleSource = (fail) => {const restatingDocumentPaths = [path.join(PLUGIN_ROOT, 'AGENTS.md'),- ...listFiles(path.join(PLUGIN_ROOT, 'skills')).filter((filePath) => filePath.endsWith('.md')),+ ...listFiles(path.join(PLUGIN_ROOT, 'skills')).filter((filePath) =>+ filePath.endsWith('.md'),+ ),];for (const documentPath of restatingDocumentPaths) {@@ -421,7 +495,9 @@ const assertOperatingRulesSingleSource = (fail) => {for (const headline of OPERATING_RULE_HEADLINES) {if (contents.includes(headline)) {- fail(`${relativePath} restates an operating rule instead of linking to operating-rules.md: ${headline}`);+ fail(+ `${relativePath} restates an operating rule instead of linking to operating-rules.md: ${headline}`,+ );}}}@@ -429,7 +505,9 @@ const assertOperatingRulesSingleSource = (fail) => {const agents = readText(path.join(PLUGIN_ROOT, 'AGENTS.md'));if (!agents.includes('references/concepts/operating-rules.md')) {- fail('AGENTS.md must point at references/concepts/operating-rules.md for the durable operating rules');+ fail(+ 'AGENTS.md must point at references/concepts/operating-rules.md for the durable operating rules',+ );}// Headlines catch a copied rule list. Copied prose is the other way a second@@ -439,7 +517,9 @@ const assertOperatingRulesSingleSource = (fail) => {const ruleBodySentences = operatingRules.split('\n').filter((line) => /^\d+\.\s+\*\*/.test(line))- .flatMap((line) => line.replace(/^\d+\.\s+\*\*[^*]+\*\*\s*/, '').split('. '))+ .flatMap((line) =>+ line.replace(/^\d+\.\s+\*\*[^*]+\*\*\s*/, '').split('. '),+ ).map((sentence) => sentence.trim()).filter((sentence) => sentence.length >= 60);@@ -449,7 +529,9 @@ const assertOperatingRulesSingleSource = (fail) => {for (const sentence of ruleBodySentences) {if (contents.includes(sentence)) {- fail(`${relativePath} copies a sentence from operating-rules.md instead of linking to it: "${sentence.slice(0, 60)}..."`);+ fail(+ `${relativePath} copies a sentence from operating-rules.md instead of linking to it: "${sentence.slice(0, 60)}..."`,+ );}}}diff --git a/packages/twenty-agent-skills/scripts/validators/references.js b/packages/twenty-agent-skills/scripts/validators/references.jsindex 581a71c9485..949ca7828b7 100644--- a/packages/twenty-agent-skills/scripts/validators/references.js+++ b/packages/twenty-agent-skills/scripts/validators/references.js@@ -32,7 +32,10 @@ const assertReferences = (fail) => {};const assertHowAppsWork = (fail) => {- const howAppsWorkPath = path.join(PLUGIN_ROOT, 'references/concepts/how-apps-work.md');+ const howAppsWorkPath = path.join(+ PLUGIN_ROOT,+ 'references/concepts/how-apps-work.md',+ );if (!fs.existsSync(howAppsWorkPath)) {fail('required reference is missing: references/concepts/how-apps-work.md');@@ -51,7 +54,7 @@ const assertHowAppsWork = (fail) => {'## Twenty Instances And Remotes','## Local Development Environment','## App Lifecycle',- 'create-twenty-app',+ 'twenty app init','## Front Component Rendering','Remote DOM','## App File Structure',@@ -97,8 +100,4 @@ const assertHowAppsWork = (fail) => {}};-export {- REQUIRED_REFERENCES,- assertReferences,- assertHowAppsWork,-};+export { REQUIRED_REFERENCES, assertReferences, assertHowAppsWork };diff --git a/packages/twenty-agent-skills/skills/create-app/SKILL.md b/packages/twenty-agent-skills/skills/create-app/SKILL.mdindex 11cf9eed172..3f59c36cf1a 100644--- a/packages/twenty-agent-skills/skills/create-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/create-app/SKILL.md@@ -5,96 +5,36 @@ description: Use when the user wants to create or scaffold a new Twenty app# When To Use-Pick this skill when the user wants to start a brand-new Twenty app from scratch. Representative triggers:+Use for requests such as "create a Twenty app" or "scaffold a new app".-- "I want to build a Twenty app"-- "scaffold a new Twenty app"-- "start a new Twenty plugin / extension / integration"-- "create a CRM extension for Twenty"-- "set up a Twenty app project"-- "bootstrap a Twenty app called X"+# Create an app-Do not use this skill when the app already exists — use `develop-app` to add features, `manage-app` for sync/deploy/troubleshooting, `publish-app` for marketplace prep, or `use-twenty-mcp` to query workspace data.+Use this skill for a new app. For an existing app, use `develop-app` or `manage-app`.-# Quickstart an App+Read `../../references/concepts/how-apps-work.md` and `../../references/concepts/operating-rules.md` first.-For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.--Use this as the default way to start an app unless the user gives different instructions.--## Why A Twenty Instance Is Needed--Before scaffolding, explain to the user that a Twenty app is not a standalone application — it is a package that extends a running Twenty instance. During development, the app's entities (objects, views, front components, logic functions) are synced to a Twenty instance where they are registered, rendered, and executed. Without a connected instance, there is nothing to sync to, no workspace to test in, and no way to verify the app works.--## Choose A Twenty Instance--By default, ask the user for the URL of their existing Twenty instance (e.g. `https://app.twenty.com` or a self-hosted URL). Mention that if they don't have one yet, you can spin up a local instance with Docker instead.--The two options are:--1. **Existing Twenty instance (default)** — the user provides the URL of a running Twenty server (self-hosted or cloud, e.g. `https://app.twenty.com`). The scaffolder authenticates via OAuth on that instance. Best when the user already has a workspace with data they want to develop against.-2. **Local instance with Docker (fallback)** — only when the user has no Twenty instance available. The scaffolder starts a disposable local Twenty server on `http://localhost:2020` through Docker. Requires Docker Desktop to be installed and running.--If the user does not provide a URL, ask first whether they have a Twenty instance URL to use; only fall back to Docker if they explicitly say they don't have one.--Before scaffolding, repeat back the app's purpose in one sentence and its expected shape: standard objects extended, any custom objects, whether it needs UI, whether it needs workflows or post-install seeding. Scaffolding is one-way — confirming here avoids re-scaffolds later.--## Scaffolding--First, ask the user for the app name if they did not provide one.--The directory name must contain only lowercase letters, numbers, and hyphens. Transform the entered name to lowercase and replace spaces with hyphens when needed.--For an existing Twenty instance (default):+Confirm the app's name and purpose. Use the standalone CLI:```bash-npx create-twenty-app@latest <app-name> --url <twenty-instance-url>+npm install -g twenty+twenty app init <app-name>+cd <app-name>+yarn install```-The `--url` flag authenticates via OAuth on the provided instance. The scaffolder opens a browser for the OAuth flow, then stores the credentials as a remote in `~/.twenty/config.json`.+`app init` only writes files. It does not install dependencies, initialize Git, start Docker, authenticate, or perform an initial sync. `create-twenty-app` is deprecated; use the standalone CLI for new apps.-Only if the user has no Twenty instance and wants to try locally with Docker:+Use `--path <directory>` for a different destination and `--display-name` or `--description` for metadata. The positional name is the package name.-```bash-npx create-twenty-app@latest <app-name>-```--This omits `--url` and starts a disposable local Twenty server through Docker.--The scaffolder handles everything: it creates the project, enables corepack, installs dependencies, initializes Git, authenticates with the target instance, runs an initial sync, and opens the generated app page when possible.--If the user provides a package name, display name, or description, pass them through:+Twenty Cloud and self-hosted instances are supported. Ask for the existing Twenty workspace URL when connection is needed. If the user wants a local server, use the documented Docker or repository development environment; the CLI has no `docker:*` commands.```bash-npx create-twenty-app@latest <app-directory> --name "<package-name>" --display-name "<display-name>" --description "<description>"+twenty auth login --url <twenty-instance-url> --name dev+twenty app apply --create --remote dev```-Supported create-time options are `--name`, `--display-name`, `--description`, `--url`, and `--authentication-method`.--## After Scaffolding--When the scaffolder completes, the app is fully created, synced, and installed. The job is done.--Do not run any follow-up validation commands after scaffolding unless the user asks for them. Do not run `yarn twenty apply`, `yarn test`, `yarn lint`, or other validation just to prove the scaffold worked; the scaffolder already performed the initial sync. If the user asks to run tests later, switch to `develop-app` or `manage-app` guidance and run the full suite against the isolated test instance with `TWENTY_API_URL=http://localhost:2021`.--Report to the user that the app was created successfully and is ready for development. Then stop. Wait for the user to ask for the next action.--The scaffolder generates a placeholder page at `src/front-components/main-page.tsx` plus its page layout and navigation menu item. In `develop-app`, delete all three before the first deploy unless the app actually needs UI. Do not stack additional pages on top of the placeholder.--It also generates a health check at `src/logic-functions/health-check.ts` that reports `OK`. Customise that file when the app gains something worth reporting; do not add a second one, since an app may declare only one health check and a second fails the build.--## Docker Fallback Troubleshooting--Use this only when the user opted into the Docker fallback and it fails because Docker is missing or not running.--The preferred recovery is to ask the user for an existing Twenty instance URL and rerun the scaffolder with `--url <twenty-instance-url>` — this skips Docker entirely.--If the user still wants the local Docker path and Docker is missing, share this download link: `https://www.docker.com/products/docker-desktop/` and ask them to install Docker Desktop.--# Next Steps+Only claim the app is installed after apply succeeds. If the request is just scaffolding, stop after the files and dependencies are created. Do not run broad validation unless requested. For integration tests, use the isolated test instance described in `../../references/develop-app/tests.md`.-Only proceed to these when the user explicitly asks:+The template includes a main page, its layout and navigation item, and a health-check function. Remove the placeholder page with its layout and navigation if the app needs no UI. Extend the existing health check rather than declaring a second one.-- Use `develop-app` when the user wants to add objects, fields, logic functions, roles, views, navigation, page layouts, skills, agents, front component registrations, or settings menu items.-- Use `../../references/design/front-component-ui.md` when the user wants to design or improve the UI of a Twenty front component.-- When the user later makes changes to app entities, use `yarn twenty apply` to sync those changes. See the `manage-app` skill for sync workflow.+After creation, use `develop-app` for entities and UI, `manage-app` for bounded sync with `twenty app apply`, and `publish-app` for release work.diff --git a/packages/twenty-agent-skills/skills/develop-app/SKILL.md b/packages/twenty-agent-skills/skills/develop-app/SKILL.mdindex cb7bfbf042f..bbf932b5a63 100644--- a/packages/twenty-agent-skills/skills/develop-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/develop-app/SKILL.md@@ -5,7 +5,7 @@ description: Use when the user wants to add or modify Twenty app entities, inclu# When To Use-Pick this skill when the user wants to change what an existing Twenty app *does* — its data model, UI, logic, or workflows. Representative triggers:+Pick this skill when the user wants to change what an existing Twenty app _does_ — its data model, UI, logic, or workflows. Representative triggers:- "add a new object to my Twenty app"- "create a logic function that runs on record create"@@ -75,7 +75,7 @@ Use a CLI to add new entities. It generates the correct file structure, UUIDs, Scommand -v twenty && twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input```-Otherwise run `yarn twenty dev:add` in an interactive terminal. The full order of options, including what to do when neither CLI can run, is rule 3 of the operating rules linked above.+Install the standalone CLI if missing. Use `twenty app add` for supported types; for other entities, follow rule 3 of the operating rules linked above and the corresponding SDK definition.## Front Component Defaults@@ -88,12 +88,12 @@ Before creating or editing front component UI, read `../../references/develop-apOnce all edits for the change are complete, run lint and typecheck once at the end (not after each individual edit), then sync the app to the active remote:```bash-yarn twenty dev:typecheck+twenty app typecheckyarn lint-yarn twenty apply+twenty app apply```-`yarn twenty dev:typecheck` checks generated app types, `yarn lint` checks local lint rules, and `yarn twenty apply` syncs entity definitions to the active remote. Run all three a single time once every edit is done, not repeatedly after each step. When the user explicitly asks to run tests, follow `../../references/develop-app/tests.md`.+`twenty app typecheck` checks generated app types, `yarn lint` checks local lint rules, and `twenty app apply` syncs entity definitions to the active remote. Run all three a single time once every edit is done, not repeatedly after each step. When the user explicitly asks to run tests, follow `../../references/develop-app/tests.md`.Use the official Twenty docs or local SDK source when exact entity fields, imports, or configuration shapes matter.diff --git a/packages/twenty-agent-skills/skills/manage-app/SKILL.md b/packages/twenty-agent-skills/skills/manage-app/SKILL.mdindex 51d4102f188..a499ab52fe4 100644--- a/packages/twenty-agent-skills/skills/manage-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/manage-app/SKILL.md@@ -45,7 +45,7 @@ Inspect current app and scripts before running operational commands:```bashsed -n '1,220p' package.json-yarn twenty remote:list+twenty remote list```Treat deploys, uninstalls, production remote changes, and production syncs as externally visible actions. Ask for explicit confirmation before running them when the target is production or user data could be affected.@@ -55,7 +55,7 @@ For command details, remotes, validation command semantics, sync modes, troublesIf the user asks to run tests, also read `../../references/develop-app/tests.md` before running any test command. Full test suites include integration tests that install and uninstall the app on their target server, so start or verify the isolated test instance and run:```bash-yarn twenty docker:start --test+docker start twenty-app-dev-testTWENTY_API_URL=http://localhost:2021 yarn test```@@ -63,25 +63,25 @@ Do not run integration tests against the dev instance on `http://localhost:2020`# Remotes-A remote is a Twenty server that the app can sync or deploy to. Credentials are stored locally in `~/.twenty/config.json`.+A remote is a Twenty server that the app can sync or deploy to. Credentials are managed by the standalone CLI. Use `twenty auth login` and `twenty remote list`.Common commands:```bash# Add a remote interactively.-yarn twenty remote:add+twenty auth login# Connect to a local Twenty server.-yarn twenty remote:add --local+twenty auth login --url http://localhost:2020# Add a remote non-interactively.-yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production+printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://your-twenty-server.com --name production# List configured remotes.-yarn twenty remote:list+twenty remote list# Switch the active remote.-yarn twenty remote:use <name>+twenty remote use <name>```When the user says "prod", "production", or "workspace de prod", identify the target remote before syncing or deploying. If it is missing, add it with `--as production` or the user-provided name.@@ -91,10 +91,10 @@ When the user says "prod", "production", or "workspace de prod", identify the taAlways use bounded apply to synchronize app changes with the active remote:```bash-yarn twenty apply+twenty app apply```-Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty apply` each time changes need to be synced.+Do not use bare `twenty app dev` (watch mode). Run `twenty app apply` each time changes need to be synced.Bounded apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.@@ -114,33 +114,33 @@ Collect the minimum useful context before changing configuration:```bashsed -n '1,220p' package.jsonsed -n '1,220p' src/application-config.ts-yarn twenty remote:list-yarn twenty apply --verbose+twenty remote list+twenty app apply --json```For remote or authentication issues:- Check that the active remote is the intended workspace or server.-- Re-run `yarn twenty remote:add --local` for local app-dev servers.-- Re-run `yarn twenty remote:add --url <url> --as <name>` for remote servers.+- Re-run `twenty auth login --url http://localhost:2020` for local app-dev servers.+- Re-run `twenty auth login --url <url> --name <name>` for remote servers.- Avoid overwriting a production remote until the target URL is confirmed.For sync issues:-- Prefer `yarn twenty apply --verbose` to get a bounded failure.+- Prefer `twenty app apply --json` to get a bounded failure.- Check generated type or schema errors before editing app entities.- If the app depends on a changed data model, use `$develop-app` to fix the entity definitions.For build or deploy issues:-- Run `yarn twenty dev:build` before `yarn twenty app:publish --private` or `yarn twenty app:publish`.+- Run `twenty app build` before `twenty app publish --private` or `twenty app publish`.- Check `package.json` version when updating an already deployed app.-- Confirm the target with `yarn twenty app:publish --private --remote <name>` instead of relying on the active remote when production is involved.+- Confirm the target with `twenty app publish --private --remote <name>` instead of relying on the active remote when production is involved.For runtime behavior:-- Use `yarn twenty dev:function:logs` to inspect function execution logs.-- Use `yarn twenty dev:function:exec -n <function-name> -p '<json>'` to reproduce a logic function with a controlled payload.+- Use `twenty app logs` to inspect function execution logs.+- Use `twenty app exec --name <function-name> --payload '<json>'` to reproduce a logic function with a controlled payload.For CI/CD failures:@@ -153,18 +153,18 @@ For CI/CD failures:Build before deploy when the user asks for release readiness or when debugging packaging issues:```bash-yarn twenty dev:build+twenty app build```Publish an app to npm, or publish privately to a configured Twenty server registry:```bash-yarn twenty app:publish-yarn twenty app:publish --private --remote production-yarn twenty app:install --remote production+twenty app publish+twenty app publish --private --remote production+twenty app install --remote production```-Before deploying an update, check that `package.json` has a strictly higher semver `version` than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with `yarn twenty app:install` when the target workspace should use it.+Before deploying an update, check that `package.json` has a strictly higher semver `version` than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with `twenty app install` when the target workspace should use it.Use `$publish-app` instead when the user wants npm marketplace publishing, listing copy, screenshots, or public app store metadata.@@ -173,27 +173,27 @@ Use `$publish-app` instead when the user wants npm marketplace publishing, listiUse function logs when debugging runtime behavior on the connected server:```bash-yarn twenty dev:function:logs-yarn twenty dev:function:logs -n <function-name>+twenty app logs+twenty app logs --name <function-name>```Run a logic function manually when testing behavior without its trigger:```bash-yarn twenty dev:function:exec -n <function-name>-yarn twenty dev:function:exec -n <function-name> -p '{"key":"value"}'+twenty app exec --name <function-name>+twenty app exec --name <function-name> --payload '{"key":"value"}'```Uninstall only after confirmation:```bash-yarn twenty app:uninstall-yarn twenty app:uninstall --yes+twenty app uninstall+twenty app uninstall --yes```# CI/CD-Apps generated with `create-twenty-app` can use GitHub Actions for CI and CD. For deployment automation, check the app's `.github/workflows/` files and configure:+Apps generated with `twenty app init` can use GitHub Actions for CI and CD. For deployment automation, check the app's `.github/workflows/` files and configure:- `TWENTY_DEPLOY_URL`- `TWENTY_DEPLOY_API_KEY`diff --git a/packages/twenty-agent-skills/skills/publish-app/SKILL.md b/packages/twenty-agent-skills/skills/publish-app/SKILL.mdindex 49d899977e8..5e0347e2472 100644--- a/packages/twenty-agent-skills/skills/publish-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/publish-app/SKILL.md@@ -5,7 +5,7 @@ description: Use when the user wants to prepare or verify a Twenty app for npm o# When To Use-Pick this skill when the user wants to make an existing Twenty app *presentable* — listing copy, branding, public assets, and publication. Representative triggers:+Pick this skill when the user wants to make an existing Twenty app _presentable_ — listing copy, branding, public assets, and publication. Representative triggers:- "prepare my Twenty app for the marketplace"- "write the README for my Twenty app"@@ -30,7 +30,7 @@ Keep the skill workflow concise:- In `defineApplication()`, verify marketplace-facing fields such as `displayName`, `description`, `author`, `category`, `logo`, `galleryImages`, `aboutDescription`, `websiteUrl`, `termsUrl`, `emailSupport`, and `issueReportUrl`.- Keep `logo` and `galleryImages` pointed at files in `public/`. Public assets must not contain secrets, private data, customer records, real tokens, or unreleased confidential material.- Remember that if `aboutDescription` is omitted, the marketplace uses the package `README.md` from npm for the About content. The About tab renders markdown text only: images and raw HTML are not rendered.-- Validate with `yarn twenty dev:build`; publish with `yarn twenty app:publish` or `yarn twenty app:publish --tag <tag>`.+- Validate with `twenty app build`; publish with `twenty app publish` or `twenty app publish --tag <tag>`.# Boundariesdiff --git a/packages/twenty-apps/examples/document-generator/src/__tests__/global-setup.ts b/packages/twenty-apps/examples/document-generator/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/examples/document-generator/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/examples/document-generator/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/examples/document-generator/src/__tests__/run-twenty.ts b/packages/twenty-apps/examples/document-generator/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/examples/document-generator/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/examples/document-generator/src/logic-functions/handlers/generate-document-handler.ts b/packages/twenty-apps/examples/document-generator/src/logic-functions/handlers/generate-document-handler.tsindex 5bf58770136..7e89244cc82 100644--- a/packages/twenty-apps/examples/document-generator/src/logic-functions/handlers/generate-document-handler.ts+++ b/packages/twenty-apps/examples/document-generator/src/logic-functions/handlers/generate-document-handler.ts@@ -92,10 +92,6 @@ export const generateDocumentHandler = async (documentTemplates: {__args: { filter: { id: { eq: templateId } }, first: 1 },edges: {- // `body` is a RICH_TEXT field: request its Markdown projection. The- // generated client only types the composite after- // `twenty dev:generate-client` is re-run against a remote that has this- // field; until then the cast bridges the lag (drop it after regen).node: {id: true,name: true,diff --git a/packages/twenty-apps/examples/document-generator/tsconfig.json b/packages/twenty-apps/examples/document-generator/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/examples/document-generator/tsconfig.json+++ b/packages/twenty-apps/examples/document-generator/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/examples/hello-world/README.md b/packages/twenty-apps/examples/hello-world/README.mdindex a864a490d7a..7daab5c9fcd 100644--- a/packages/twenty-apps/examples/hello-world/README.md+++ b/packages/twenty-apps/examples/hello-world/README.md@@ -1,39 +1,39 @@-This is a [Twenty](https://twenty.com) application project bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).+This is a [Twenty](https://twenty.com) application project developed with the [Twenty CLI](https://www.npmjs.com/package/twenty).## Getting StartedFirst, authenticate to your workspace:```bash-yarn twenty remote:add --api-url http://localhost:2020 --as local+twenty auth login --url http://localhost:2020 --name local```Then, start development mode to sync your app and watch for changes:```bash-yarn twenty dev+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:+Run `twenty --help` to list all available commands. Common commands:```bash# Remotes & Authentication-yarn twenty remote:add --api-url http://localhost:2020 --as local # Authenticate with Twenty-yarn twenty remote:status # Check auth status-yarn twenty remote:use # Set default remote-yarn twenty remote:list # List all configured remotes-yarn twenty remote:remove <name> # Remove a remote+twenty auth login --url http://localhost:2020 --name local # Authenticate with Twenty+twenty auth status # Check auth status+twenty remote use # Set default remote+twenty remote list # List all configured remotes+twenty remote remove <name> # Remove a remote# Application-yarn twenty dev # Start dev mode (watch, build, sync, and auto-generate typed client)-yarn twenty dev:add # Scaffold a new entity (object, field, function, front-component, role, view, navigation-menu-item)-yarn twenty dev:function:logs # Stream function logs-yarn twenty dev:function:exec # Execute a function with JSON payload-yarn twenty app:uninstall # Uninstall app from workspace+twenty app dev # Start dev mode (watch, build, sync, and auto-generate typed client)+twenty app add # Scaffold a new entity (object, field, function, front-component, role, view, navigation-menu-item)+twenty app logs # Stream function logs+twenty app exec # Execute a function with JSON payload+twenty app uninstall # Uninstall app from workspace```## Integration Testsdiff --git a/packages/twenty-apps/examples/hello-world/src/__tests__/app-install.integration-test.ts b/packages/twenty-apps/examples/hello-world/src/__tests__/app-install.integration-test.tsindex 58002036a4b..371722a95d6 100644--- a/packages/twenty-apps/examples/hello-world/src/__tests__/app-install.integration-test.ts+++ b/packages/twenty-apps/examples/hello-world/src/__tests__/app-install.integration-test.ts@@ -1,51 +1,25 @@import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';-import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';+import { runTwenty } from './run-twenty';import { MetadataApiClient } from 'twenty-client-sdk/metadata';import { afterAll, beforeAll, describe, expect, it } from 'vitest';-const APP_PATH = process.cwd();-describe('App installation', () => {beforeAll(async () => {- const buildResult = await appBuild({- appPath: APP_PATH,- tarball: true,- onProgress: (message: string) => console.log(`[build] ${message}`),- });-- if (!buildResult.success) {- throw new Error(- `Build failed: ${buildResult.error?.message ?? 'Unknown error'}`,- );- }-- const deployResult = await appDeploy({- tarballPath: buildResult.data.tarballPath!,- onProgress: (message: string) => console.log(`[deploy] ${message}`),- });-- if (!deployResult.success) {- throw new Error(- `Deploy failed: ${deployResult.error?.message ?? 'Unknown error'}`,- );- }-- const installResult = await appInstall({ appPath: APP_PATH });-- if (!installResult.success) {- throw new Error(- `Install failed: ${installResult.error?.message ?? 'Unknown error'}`,- );+ for (const args of [+ ['app', 'publish', '--private'],+ ['app', 'install'],+ ]) {+ const result = await runTwenty(args);+ if (!result.ok) {+ throw new Error(`${args.join(' ')} failed: ${result.error.message}`);+ }}});afterAll(async () => {- const uninstallResult = await appUninstall({ appPath: APP_PATH });-- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,- );+ const result = await runTwenty(['app', 'uninstall', '--yes']);+ if (!result.ok) {+ console.warn(`App uninstall failed: ${result.error.message}`);}});@@ -62,8 +36,7 @@ describe('App installation', () => {const installedApp = result.findManyApplications.find((application: { universalIdentifier: string }) =>- application.universalIdentifier ===- APPLICATION_UNIVERSAL_IDENTIFIER,+ application.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,);expect(installedApp).toBeDefined();diff --git a/packages/twenty-apps/examples/hello-world/src/__tests__/run-twenty.ts b/packages/twenty-apps/examples/hello-world/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/examples/hello-world/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/examples/hello-world/src/__tests__/setup-test.ts b/packages/twenty-apps/examples/hello-world/src/__tests__/setup-test.tsindex bfc05cb8002..ce0b53660c5 100644--- a/packages/twenty-apps/examples/hello-world/src/__tests__/setup-test.ts+++ b/packages/twenty-apps/examples/hello-world/src/__tests__/setup-test.ts@@ -1,11 +1,5 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';import { beforeAll } from 'vitest';-const CONFIG_DIR = path.join(os.homedir(), '.twenty');-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.test.json');-beforeAll(async () => {const apiUrl = process.env.TWENTY_API_URL!;const token = process.env.TWENTY_API_KEY!;@@ -13,7 +7,6 @@ beforeAll(async () => {if (!apiUrl || !token) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -33,21 +26,5 @@ beforeAll(async () => {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}- fs.mkdirSync(CONFIG_DIR, { recursive: true });-- fs.writeFileSync(- CONFIG_PATH,- JSON.stringify(- {- remotes: {- local: { apiUrl, apiKey: token },- },- defaultRemote: 'local',- },- null,- 2,- ),- );-process.env.TWENTY_APP_ACCESS_TOKEN ??= token;});diff --git a/packages/twenty-apps/examples/hello-world/src/front-components/hello-world.tsx b/packages/twenty-apps/examples/hello-world/src/front-components/hello-world.tsxindex 85f557e3d14..ce83f0806a8 100644--- a/packages/twenty-apps/examples/hello-world/src/front-components/hello-world.tsx+++ b/packages/twenty-apps/examples/hello-world/src/front-components/hello-world.tsx@@ -1,5 +1,5 @@import { useEffect, useState } from 'react';-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';+import { CoreApiClient } from 'twenty-client-sdk/core';import { defineFrontComponent } from 'twenty-sdk/define';export const HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER =@@ -8,7 +8,7 @@ export const HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER =export const HelloWorld = () => {const client = new CoreApiClient();const [data, setData] = useState<- Pick<CoreSchema.Company, 'name' | 'id'> | undefined+ { id: string; name: string | null } | null | undefined>(undefined);useEffect(() => {diff --git a/packages/twenty-apps/examples/hello-world/tsconfig.json b/packages/twenty-apps/examples/hello-world/tsconfig.jsonindex 83342568e55..0ff094dffe9 100644--- a/packages/twenty-apps/examples/hello-world/tsconfig.json+++ b/packages/twenty-apps/examples/hello-world/tsconfig.json@@ -18,32 +18,21 @@"strictBindCallApply": false,"target": "es2018","module": "esnext",- "lib": [- "es2020",- "dom"- ],+ "lib": ["es2020", "dom"],"skipLibCheck": true,"skipDefaultLibCheck": true,"resolveJsonModule": true,"paths": {- "src/*": [- "./src/*"- ],- "~/*": [- "./*"- ]+ "src/*": ["./src/*"],+ "~/*": ["./*"]}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]-}\ No newline at end of file+}diff --git a/packages/twenty-apps/examples/hello-world/tsconfig.spec.json b/packages/twenty-apps/examples/hello-world/tsconfig.spec.jsonindex 7dc5cee985c..ea69a6c0105 100644--- a/packages/twenty-apps/examples/hello-world/tsconfig.spec.json+++ b/packages/twenty-apps/examples/hello-world/tsconfig.spec.json@@ -2,16 +2,8 @@"extends": "./tsconfig.json","compilerOptions": {"composite": true,- "types": [- "vitest/globals"- ]+ "types": ["vitest/globals", "node"]},- "include": [- "src/**/*.ts",- "src/**/*.tsx"- ],- "exclude": [- "node_modules",- "dist"- ]-}\ No newline at end of file+ "include": ["src/**/*.ts", "src/**/*.tsx"],+ "exclude": ["node_modules", "dist"]+}diff --git a/packages/twenty-apps/examples/postcard/README.md b/packages/twenty-apps/examples/postcard/README.mdindex 353fc92efdd..9d0af29dccc 100644--- a/packages/twenty-apps/examples/postcard/README.md+++ b/packages/twenty-apps/examples/postcard/README.md@@ -6,26 +6,26 @@ A rich example app showcasing all Twenty app entity types. Use this as a referenThis app demonstrates every entity type available in the Twenty SDK:-| Entity | Files | What it shows |-|--------|-------|---------------|-| **Application** | `src/application.config.ts` | App metadata, application variables, server variables |-| **Objects** | `src/objects/` | Custom objects with inline fields, junction tables |-| **Fields** | `src/fields/` | Standalone fields, relations (ONE_TO_MANY, MANY_TO_ONE), extending standard objects |-| **Logic Functions** | `src/logic-functions/` | HTTP routes, database event triggers, cron schedules, tool functions, install hooks |-| **Front Components** | `src/components/` | React components rendered inside Twenty's UI |-| **Roles** | `src/roles/` | Permission roles with object and field-level access control |-| **Views** | `src/views/` | Saved table views with column configuration |-| **Navigation** | `src/navigation-menu-items/` | Sidebar links targeting views |-| **Skills** | `src/skills/` | AI skill providing context to agents |-| **Agents** | `src/agents/` | AI agent with a system prompt |-| **Page Layouts** | `src/page-layouts/` | Custom record page with a front component widget |+| Entity | Files | What it shows |+| -------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |+| **Application** | `src/application.config.ts` | App metadata, application variables, server variables |+| **Objects** | `src/objects/` | Custom objects with inline fields, junction tables |+| **Fields** | `src/fields/` | Standalone fields, relations (ONE_TO_MANY, MANY_TO_ONE), extending standard objects |+| **Logic Functions** | `src/logic-functions/` | HTTP routes, database event triggers, cron schedules, tool functions, install hooks |+| **Front Components** | `src/components/` | React components rendered inside Twenty's UI |+| **Roles** | `src/roles/` | Permission roles with object and field-level access control |+| **Views** | `src/views/` | Saved table views with column configuration |+| **Navigation** | `src/navigation-menu-items/` | Sidebar links targeting views |+| **Skills** | `src/skills/` | AI skill providing context to agents |+| **Agents** | `src/agents/` | AI agent with a system prompt |+| **Page Layouts** | `src/page-layouts/` | Custom record page with a front component widget |## Getting started```bash# From this directoryyarn install-yarn twenty dev+twenty app dev```## Learn morediff --git a/packages/twenty-apps/examples/postcard/src/__tests__/global-setup.ts b/packages/twenty-apps/examples/postcard/src/__tests__/global-setup.tsindex fba2a3f3bba..9426fbbf8b3 100644--- a/packages/twenty-apps/examples/postcard/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/examples/postcard/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});-- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });+ const result = await runTwenty(['app', 'apply', '--create']);- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {throw new Error(- `App uninstall failed during teardown: ${JSON.stringify(uninstallResult.error, null, 2)}`,+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/examples/postcard/src/__tests__/run-twenty.ts b/packages/twenty-apps/examples/postcard/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/examples/postcard/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/examples/postcard/tsconfig.json b/packages/twenty-apps/examples/postcard/tsconfig.jsonindex 20c8d89f95e..816da62f6f0 100644--- a/packages/twenty-apps/examples/postcard/tsconfig.json+++ b/packages/twenty-apps/examples/postcard/tsconfig.json@@ -28,6 +28,7 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","e2e",@@ -35,10 +36,5 @@"**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/fixtures/function-execute-app/README.md b/packages/twenty-apps/fixtures/function-execute-app/README.mdindex 7a157643064..0f7edbcb0fb 100644--- a/packages/twenty-apps/fixtures/function-execute-app/README.md+++ b/packages/twenty-apps/fixtures/function-execute-app/README.md@@ -1,3 +1,11 @@# Function Execute Test App-Fixture app used to exercise logic-function execution in SDK tests.+Fixture app used to exercise logic-function execution in CLI tests.++Build the standalone CLI from the repository root before using this fixture's `dev`, `exec`, or `uninstall` scripts:++```bash+npx nx build twenty-cli+```++The scripts invoke that local build directly, so the SDK binary cannot shadow it.diff --git a/packages/twenty-apps/fixtures/function-execute-app/package.json b/packages/twenty-apps/fixtures/function-execute-app/package.jsonindex 3cf46866cbb..fc158c50946 100644--- a/packages/twenty-apps/fixtures/function-execute-app/package.json+++ b/packages/twenty-apps/fixtures/function-execute-app/package.json@@ -9,9 +9,9 @@},"packageManager": "[email protected]","scripts": {- "dev": "twenty dev",- "exec": "twenty dev:fn-exec",- "uninstall": "twenty app:uninstall",+ "dev": "node ../../../twenty-cli/dist/cli.cjs app dev",+ "exec": "node ../../../twenty-cli/dist/cli.cjs app exec",+ "uninstall": "node ../../../twenty-cli/dist/cli.cjs app uninstall","lint": "oxlint -c .oxlintrc.json .","lint:fix": "oxlint --fix -c .oxlintrc.json ."},diff --git a/packages/twenty-apps/public/call-recorder/AGENTS.md b/packages/twenty-apps/public/call-recorder/AGENTS.mdindex f646709b9a2..0085c869b01 100644--- a/packages/twenty-apps/public/call-recorder/AGENTS.md+++ b/packages/twenty-apps/public/call-recorder/AGENTS.md@@ -48,19 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/call-recorder/CLAUDE.md b/packages/twenty-apps/public/call-recorder/CLAUDE.mdindex f646709b9a2..0085c869b01 100644--- a/packages/twenty-apps/public/call-recorder/CLAUDE.md+++ b/packages/twenty-apps/public/call-recorder/CLAUDE.md@@ -48,19 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/call-recorder/package.json b/packages/twenty-apps/public/call-recorder/package.jsonindex d0212a79682..c6f27b4d1d7 100644--- a/packages/twenty-apps/public/call-recorder/package.json+++ b/packages/twenty-apps/public/call-recorder/package.json@@ -41,6 +41,7 @@"typescript": "^5.9.3","use-debounce": "^10.0.0","vite-tsconfig-paths": "^4.2.1",- "vitest": "^4.1.9"+ "vitest": "^4.1.9",+ "zod": "^4.1.11"}}diff --git a/packages/twenty-apps/public/call-recorder/src/__tests__/build-result-schema.ts b/packages/twenty-apps/public/call-recorder/src/__tests__/build-result-schema.tsnew file mode 100644index 00000000000..9812700e3cb--- /dev/null+++ b/packages/twenty-apps/public/call-recorder/src/__tests__/build-result-schema.ts@@ -0,0 +1,16 @@+import { z } from 'zod';++import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++export const buildResultSchema = z.object({+ manifest: z.looseObject({+ application: z.looseObject({+ universalIdentifier: z.literal(APPLICATION_UNIVERSAL_IDENTIFIER),+ }),+ logicFunctions: z+ .array(z.looseObject({ universalIdentifier: z.string().min(1) }))+ .min(1),+ }),+});++export type BuildManifest = z.infer<typeof buildResultSchema>['manifest'];diff --git a/packages/twenty-apps/public/call-recorder/src/__tests__/call-recorder-lifecycle.integration-test.ts b/packages/twenty-apps/public/call-recorder/src/__tests__/call-recorder-lifecycle.integration-test.tsindex ee6cb6f86ab..74d95002ac1 100644--- a/packages/twenty-apps/public/call-recorder/src/__tests__/call-recorder-lifecycle.integration-test.ts+++ b/packages/twenty-apps/public/call-recorder/src/__tests__/call-recorder-lifecycle.integration-test.ts@@ -911,6 +911,7 @@ describe('call recorder app lifecycle (integration)', () => {beforeEach(() => {recall = new FakeRecallApi();+ nextCalendarEventFixtureIndex = 0;nextArtifactImportRequestIndex = 0;nextFollowUpIndex = 0;diff --git a/packages/twenty-apps/public/call-recorder/src/__tests__/disable-automatic-triggers-or-throw.ts b/packages/twenty-apps/public/call-recorder/src/__tests__/disable-automatic-triggers-or-throw.tsnew file mode 100644index 00000000000..28420046b42--- /dev/null+++ b/packages/twenty-apps/public/call-recorder/src/__tests__/disable-automatic-triggers-or-throw.ts@@ -0,0 +1,63 @@+import { MetadataApiClient } from 'twenty-client-sdk/metadata';+import { isDefined } from 'twenty-sdk/utils';++import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++import { type BuildManifest } from './build-result-schema';++export const disableAutomaticTriggersOrThrow = async (+ manifest: BuildManifest,+) => {+ const logicFunctions = manifest.logicFunctions.map((logicFunction) => ({+ ...logicFunction,+ databaseEventTriggerSettings: null,+ cronTriggerSettings: null,+ }));+ const client = new MetadataApiClient();++ // Automatic worker jobs would race the fixtures managed by these tests.+ await client.mutation({+ syncApplication: {+ __args: {+ inferDeletionFromMissingEntities: false,+ manifest: { ...manifest, logicFunctions },+ },+ applicationUniversalIdentifier: true,+ },+ });++ const { findOneApplication: application, findManyLogicFunctions } =+ await client.query({+ findOneApplication: {+ __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },+ id: true,+ },+ findManyLogicFunctions: {+ applicationId: true,+ universalIdentifier: true,+ databaseEventTriggerSettings: true,+ cronTriggerSettings: true,+ },+ });+ const installedFunctions = findManyLogicFunctions.filter(+ (logicFunction) => logicFunction.applicationId === application.id,+ );+ const expectedIdentifiers = new Set(+ logicFunctions.map((logicFunction) => logicFunction.universalIdentifier),+ );++ if (+ installedFunctions.length !== expectedIdentifiers.size ||+ installedFunctions.some(+ (logicFunction) =>+ !isDefined(logicFunction.universalIdentifier) ||+ !expectedIdentifiers.has(logicFunction.universalIdentifier) ||+ isDefined(logicFunction.databaseEventTriggerSettings) ||+ isDefined(logicFunction.cronTriggerSettings),+ )+ ) {+ throw new Error(+ 'Automatic triggers were not disabled for all call-recorder logic functions',+ );+ }+};diff --git a/packages/twenty-apps/public/call-recorder/src/__tests__/disable-automatic-triggers.test.ts b/packages/twenty-apps/public/call-recorder/src/__tests__/disable-automatic-triggers.test.tsnew file mode 100644index 00000000000..aecd4b11d13--- /dev/null+++ b/packages/twenty-apps/public/call-recorder/src/__tests__/disable-automatic-triggers.test.ts@@ -0,0 +1,155 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++import { buildResultSchema } from './build-result-schema';+import { disableAutomaticTriggersOrThrow } from './disable-automatic-triggers-or-throw';++const { query, mutation } = vi.hoisted(() => ({+ query: vi.fn(),+ mutation: vi.fn(),+}));++vi.mock('twenty-client-sdk/metadata', () => ({+ MetadataApiClient: class {+ query = query;+ mutation = mutation;+ },+}));++const logicFunction = {+ universalIdentifier: '22222222-2222-4222-8222-222222222222',+ builtHandlerPath: 'logic-functions/reconcile.mjs',+ builtHandlerChecksum: 'checksum',+ databaseEventTriggerSettings: { eventName: 'calendarEvent.*' },+ cronTriggerSettings: { pattern: '* * * * *' },+ httpRouteTriggerSettings: { path: '/webhook', httpMethod: 'POST' },+};+const manifest = {+ application: {+ universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,+ name: 'Call recorder',+ },+ logicFunctions: [logicFunction],+ fields: [{ name: 'callRecorderPreference' }],+};+const installedFunction = {+ ...logicFunction,+ applicationId: 'call-recorder',+ databaseEventTriggerSettings: null,+ cronTriggerSettings: null,+};++type InstalledFunction = {+ applicationId: string;+ universalIdentifier: string;+ databaseEventTriggerSettings:+ | typeof logicFunction.databaseEventTriggerSettings+ | null;+ cronTriggerSettings: typeof logicFunction.cronTriggerSettings | null;+};++const mockInstalledFunctions = (logicFunctions: InstalledFunction[]) => {+ query.mockResolvedValue({+ findOneApplication: { id: 'call-recorder' },+ findManyLogicFunctions: logicFunctions,+ });+};++describe('lifecycle trigger isolation', () => {+ beforeEach(() => {+ vi.resetAllMocks();+ mockInstalledFunctions([installedFunction]);+ });++ it('disables and verifies automatic delivery while preserving the built handlers', async () => {+ mockInstalledFunctions([+ installedFunction,+ { ...logicFunction, applicationId: 'another-app' },+ ]);++ await disableAutomaticTriggersOrThrow(+ buildResultSchema.parse({ manifest }).manifest,+ );++ expect(mutation).toHaveBeenCalledWith({+ syncApplication: {+ __args: {+ inferDeletionFromMissingEntities: false,+ manifest: {+ ...manifest,+ logicFunctions: [+ {+ ...logicFunction,+ databaseEventTriggerSettings: null,+ cronTriggerSettings: null,+ },+ ],+ },+ },+ applicationUniversalIdentifier: true,+ },+ });+ expect(query).toHaveBeenCalledWith({+ findOneApplication: {+ __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },+ id: true,+ },+ findManyLogicFunctions: {+ applicationId: true,+ universalIdentifier: true,+ databaseEventTriggerSettings: true,+ cronTriggerSettings: true,+ },+ });+ expect(logicFunction.databaseEventTriggerSettings).toEqual({+ eventName: 'calendarEvent.*',+ });+ });++ it.each(+ [undefined, [], [null]].map((logicFunctions) => ({ logicFunctions })),+ )('rejects incomplete manifests before syncing: %j', ({ logicFunctions }) => {+ expect(() =>+ buildResultSchema.parse({ manifest: { ...manifest, logicFunctions } }),+ ).toThrow();+ expect(mutation).not.toHaveBeenCalled();+ });++ it('rejects a manifest belonging to another app', () => {+ expect(() =>+ buildResultSchema.parse({+ manifest: {+ ...manifest,+ application: { universalIdentifier: 'another-app' },+ },+ }),+ ).toThrow();+ expect(mutation).not.toHaveBeenCalled();+ });++ it.each(+ [+ [],+ [{ ...installedFunction, universalIdentifier: 'unexpected-function' }],+ [+ {+ ...installedFunction,+ databaseEventTriggerSettings: { eventName: 'calendarEvent.*' },+ },+ ],+ [{ ...installedFunction, cronTriggerSettings: { pattern: '* * * * *' } }],+ ].map((functions) => ({ functions })),+ )(+ 'fails setup if the installed functions remain unsafe: %j',+ async ({ functions }) => {+ mockInstalledFunctions(functions);++ await expect(+ disableAutomaticTriggersOrThrow(+ buildResultSchema.parse({ manifest }).manifest,+ ),+ ).rejects.toThrow('Automatic triggers were not disabled');+ },+ );+});diff --git a/packages/twenty-apps/public/call-recorder/src/__tests__/global-setup.ts b/packages/twenty-apps/public/call-recorder/src/__tests__/global-setup.tsindex baa6b0ae2e9..320a58589b6 100644--- a/packages/twenty-apps/public/call-recorder/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/call-recorder/src/__tests__/global-setup.ts@@ -1,21 +1,14 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { buildResultSchema } from './build-result-schema';+import { disableAutomaticTriggersOrThrow } from './disable-automatic-triggers-or-throw';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.test.json');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -23,79 +16,49 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(CONFIG_PATH, payload);-}--function removeConfig() {- fs.rmSync(CONFIG_PATH, { force: true });-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();+ const { apiUrl } = validateEnvironmentOrThrow();- await checkServer(apiUrl);+ await checkServerOrThrow(apiUrl);+ await teardown();- writeConfig(apiUrl, apiKey);+ const build = await runTwenty(['app', 'build']);- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ if (!build.ok) {+ throw new Error('Could not build the call-recorder manifest');+ }- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });+ const { manifest } = buildResultSchema.parse(build.data);+ const result = await runTwenty(['app', 'apply', '--create']);- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}++ await disableAutomaticTriggersOrThrow(manifest);}export async function teardown() {- try {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,- );- }- } catch (error) {- console.warn(- `App uninstall failed: ${error instanceof Error ? error.message : String(error)}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);- } finally {- removeConfig();}}diff --git a/packages/twenty-apps/public/call-recorder/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/call-recorder/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/call-recorder/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/call-recorder/tsconfig.json b/packages/twenty-apps/public/call-recorder/tsconfig.jsonindex 18c32171a53..437a83800c3 100644--- a/packages/twenty-apps/public/call-recorder/tsconfig.json+++ b/packages/twenty-apps/public/call-recorder/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/call-recorder/yarn.lock b/packages/twenty-apps/public/call-recorder/yarn.lockindex f47090c9b6b..ca53d979198 100644--- a/packages/twenty-apps/public/call-recorder/yarn.lock+++ b/packages/twenty-apps/public/call-recorder/yarn.lock@@ -1408,6 +1408,7 @@ __metadata:use-debounce: "npm:^10.0.0"vite-tsconfig-paths: "npm:^4.2.1"vitest: "npm:^4.1.9"+ zod: "npm:^4.1.11"languageName: unknownlinkType: softdiff --git a/packages/twenty-apps/public/companion/AGENTS.md b/packages/twenty-apps/public/companion/AGENTS.mdindex 7629e26d549..f82c8f78a37 100644--- a/packages/twenty-apps/public/companion/AGENTS.md+++ b/packages/twenty-apps/public/companion/AGENTS.md@@ -48,23 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/companion/CLAUDE.md b/packages/twenty-apps/public/companion/CLAUDE.mdindex 7629e26d549..f82c8f78a37 100644--- a/packages/twenty-apps/public/companion/CLAUDE.md+++ b/packages/twenty-apps/public/companion/CLAUDE.md@@ -48,23 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/companion/README.md b/packages/twenty-apps/public/companion/README.mdindex 35b840f4fcd..fe32e029ba0 100644--- a/packages/twenty-apps/public/companion/README.md+++ b/packages/twenty-apps/public/companion/README.md@@ -16,7 +16,7 @@ The integration has its own application registration, default role, custom fieldDesktop requests run as the signed-in user. Processing jobs only accept recordings with a valid `companionSession`; webhook events additionally require Recall metadata `twentyRecordingSource: companion`. An installed calendar bot can coexist: Desktop Recorder checks standard scheduled/active recording state to avoid recording that event twice. It does not read Call Recorder's custom fields or invoke its functions.-The desktop uses the existing CLI OAuth client and PKCE flow from `twenty remote:add`. After sign-in it checks whether the Desktop Recorder backend is available and offers installation if needed. The app's Settings tab provides the macOS download and configuration without a dedicated page in Twenty core.+The desktop uses the existing CLI OAuth client and PKCE flow from `twenty auth login`. After sign-in it checks whether the Desktop Recorder backend is available and offers installation if needed. The app's Settings tab provides the macOS download and configuration without a dedicated page in Twenty core.## Recording processing and creditsdiff --git a/packages/twenty-apps/public/companion/src/__tests__/global-setup.ts b/packages/twenty-apps/public/companion/src/__tests__/global-setup.tsnew file mode 100644index 00000000000..7ce43b88ebd--- /dev/null+++ b/packages/twenty-apps/public/companion/src/__tests__/global-setup.ts@@ -0,0 +1,55 @@+import { isNonEmptyString } from '@sniptt/guards';++import { runTwenty } from './run-twenty';++function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {+ const apiUrl = process.env.TWENTY_API_URL;+ const apiKey = process.env.TWENTY_API_KEY;++ if (!isNonEmptyString(apiUrl) || !isNonEmptyString(apiKey)) {+ throw new Error(+ 'TWENTY_API_URL and TWENTY_API_KEY must be set.\n' ++ 'Or set them in vitest env config.',+ );+ }++ return { apiUrl, apiKey };+}++async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {+ throw new Error(+ `Twenty server is not reachable at ${apiUrl}. ` ++ 'Make sure the server is running before executing integration tests.',+ );+ });++ if (!response.ok) {+ throw new Error(`Server at ${apiUrl} returned ${response.status}`);+ }+}++export async function setup() {+ const { apiUrl } = validateEnvironmentOrThrow();++ await checkServerOrThrow(apiUrl);+ await teardown();++ const result = await runTwenty(['app', 'apply', '--create']);++ if (!result.ok) {+ throw new Error(+ `App apply failed: ${result.error.code} ${result.error.message}`,+ );+ }+}++export async function teardown() {+ const result = await runTwenty(['app', 'uninstall', '--yes']);++ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,+ );+ }+}diff --git a/packages/twenty-apps/public/companion/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/companion/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/companion/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/companion/src/__tests__/setup.ts b/packages/twenty-apps/public/companion/src/__tests__/setup.tsindex cb2c28eba7a..9cb3d712421 100644--- a/packages/twenty-apps/public/companion/src/__tests__/setup.ts+++ b/packages/twenty-apps/public/companion/src/__tests__/setup.ts@@ -1,54 +1 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';--import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.test.json');--const getRemoteConfiguration = (): { apiUrl: string; apiKey: string } => {- const apiUrl = process.env.TWENTY_API_URL;- const apiKey = process.env.TWENTY_API_KEY;-- if (!apiUrl || !apiKey) {- throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.');- }-- return { apiUrl, apiKey };-};--export const setup = async () => {- const { apiUrl, apiKey } = getRemoteConfiguration();- const response = await fetch(`${apiUrl}/healthz`);-- if (!response.ok) {- throw new Error(`Twenty returned HTTP ${response.status}`);- }-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(- CONFIG_PATH,- JSON.stringify(- {- remotes: {- local: { apiUrl, apiKey, accessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- ),- );-- await appUninstall({ appPath: APP_PATH }).catch(() => {});-- const result = await appDevOnce({ appPath: APP_PATH });-- if (!result.success) {- throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,- );- }-};+export { setup } from './global-setup';diff --git a/packages/twenty-apps/public/companion/src/__tests__/teardown.ts b/packages/twenty-apps/public/companion/src/__tests__/teardown.tsindex 44457a6c170..74e69ea4e70 100644--- a/packages/twenty-apps/public/companion/src/__tests__/teardown.ts+++ b/packages/twenty-apps/public/companion/src/__tests__/teardown.ts@@ -1,17 +1 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';--import { appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.test.json');--export const teardown = async () => {- try {- await appUninstall({ appPath: APP_PATH });- } finally {- fs.rmSync(CONFIG_PATH, { force: true });- }-};+export { teardown } from './global-setup';diff --git a/packages/twenty-apps/public/companion/tsconfig.json b/packages/twenty-apps/public/companion/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/companion/tsconfig.json+++ b/packages/twenty-apps/public/companion/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/discord/src/__tests__/global-setup.ts b/packages/twenty-apps/public/discord/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/discord/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/discord/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/discord/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/discord/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/discord/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/discord/tsconfig.json b/packages/twenty-apps/public/discord/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/discord/tsconfig.json+++ b/packages/twenty-apps/public/discord/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/exa/src/__tests__/global-setup.ts b/packages/twenty-apps/public/exa/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/exa/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/exa/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/exa/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/exa/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/exa/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/exa/tsconfig.json b/packages/twenty-apps/public/exa/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/exa/tsconfig.json+++ b/packages/twenty-apps/public/exa/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/fathom/AGENTS.md b/packages/twenty-apps/public/fathom/AGENTS.mdindex 7629e26d549..f82c8f78a37 100644--- a/packages/twenty-apps/public/fathom/AGENTS.md+++ b/packages/twenty-apps/public/fathom/AGENTS.md@@ -48,23 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/fathom/CLAUDE.md b/packages/twenty-apps/public/fathom/CLAUDE.mdindex 7629e26d549..f82c8f78a37 100644--- a/packages/twenty-apps/public/fathom/CLAUDE.md+++ b/packages/twenty-apps/public/fathom/CLAUDE.md@@ -48,23 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/fathom/SETUP.md b/packages/twenty-apps/public/fathom/SETUP.mdindex 1f1304b365a..0b0369febf5 100644--- a/packages/twenty-apps/public/fathom/SETUP.md+++ b/packages/twenty-apps/public/fathom/SETUP.md@@ -34,13 +34,7 @@ to the workspace that made the connection, so no per-workspace domain is needed.yarn install```-2. Start the local Twenty server:-- ```bash- yarn twenty docker:start- ```-- Check the server status at any time with `yarn twenty docker:status`.+2. Start a local Twenty server with Docker or the repository development setup. Install the standalone CLI with `npm install -g twenty`, then run `twenty auth login --url http://localhost:2020`.3. Set `FATHOM_CLIENT_ID` and `FATHOM_CLIENT_SECRET` as server variables inTwenty.@@ -48,7 +42,7 @@ to the workspace that made the connection, so no per-workspace domain is needed.4. Start the development server and sync your app:```bash- yarn twenty dev+ twenty app dev --create```5. Open [http://localhost:2020](http://localhost:2020), log in with the default development credentials: `[email protected]` / `[email protected]`, and connect Fathom from Settings. The connection hook registers the signed webhook and starts a 31-day import.diff --git a/packages/twenty-apps/public/fathom/package.json b/packages/twenty-apps/public/fathom/package.jsonindex 7aae185f81d..a517855221d 100644--- a/packages/twenty-apps/public/fathom/package.json+++ b/packages/twenty-apps/public/fathom/package.json@@ -31,7 +31,7 @@"@types/node": "^24.7.2","@typescript/native-preview": "^7.0.0-dev.20260116.1","oxlint": "^0.16.0",- "twenty-client-sdk": "2.38.0",+ "twenty-client-sdk": "2.50.0","twenty-sdk": "2.38.0","typescript": "^5.9.3","vite-tsconfig-paths": "^4.2.1",diff --git a/packages/twenty-apps/public/fathom/src/__tests__/deployed-functions.integration-test.ts b/packages/twenty-apps/public/fathom/src/__tests__/deployed-functions.integration-test.tsindex 3c87c3ee84c..4d6d657abd2 100644--- a/packages/twenty-apps/public/fathom/src/__tests__/deployed-functions.integration-test.ts+++ b/packages/twenty-apps/public/fathom/src/__tests__/deployed-functions.integration-test.ts@@ -1,8 +1,6 @@-import * as fs from 'fs';-import * as path from 'path';-import { MetadataApiClient } from 'twenty-client-sdk/metadata';-import { functionExecute } from 'twenty-sdk/cli';+import { executeDeployedFunctionOrThrow } from './execute-deployed-function-or-throw';+import { readManifestLogicFunctionNamesOrThrow } from './read-manifest-logic-function-names-or-throw';import { describe, expect, it } from 'vitest';// These scenarios run the functions the way the server runs them: deployed,@@ -10,27 +8,6 @@ import { describe, expect, it } from 'vitest';// Fathom account is connected on the test workspace, so every path ends at// the connection lookup, after the bundle, the SDK calls and the input// validation have run for real.-const APP_PATH = process.cwd();--const executeDeployedFunction = async (- functionName: string,- payload: Record<string, unknown>,-) => {- const result = await functionExecute({- appPath: APP_PATH,- functionName,- payload,- });-- if (!result.success) {- throw new Error(- `Could not execute ${functionName}: ${result.error.message}`,- );- }-- return result.data;-};-const buildRoutePayload = (body: Record<string, unknown>) => ({headers: {},queryStringParameters: {},@@ -40,17 +17,6 @@ const buildRoutePayload = (body: Record<string, unknown>) => ({requestContext: { http: { method: 'POST', path: '/fathom/backfill' } },});-const readManifestLogicFunctionNames = (): string[] => {- const manifest = JSON.parse(- fs.readFileSync(- path.join(APP_PATH, '.twenty', 'output', 'manifest.json'),- 'utf8',- ),- ) as { logicFunctions: { name: string }[] };-- return manifest.logicFunctions.map((logicFunction) => logicFunction.name);-};-describe('Fathom app deployed functions', () => {it('deploys every logic function the manifest declares', async () => {const deployedFunctionsResult = await new MetadataApiClient().query({@@ -61,16 +27,16 @@ describe('Fathom app deployed functions', () => {(logicFunction: { name: string }) => logicFunction.name,);- for (const manifestFunctionName of readManifestLogicFunctionNames()) {+ for (const manifestFunctionName of await readManifestLogicFunctionNamesOrThrow()) {expect(deployedFunctionNames).toContain(manifestFunctionName);}});it('rejects a backfill window outside the allowed range before touching the queue', async () => {- const execution = await executeDeployedFunction(- 'fathom-backfill',- buildRoutePayload({ days: 0 }),- );+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'fathom-backfill',+ payload: buildRoutePayload({ days: 0 }),+ });expect(execution.status).toBe('SUCCESS');expect(execution.data).toEqual({@@ -80,10 +46,10 @@ describe('Fathom app deployed functions', () => {});it('reports the missing Fathom connection from the deployed backfill route', async () => {- const execution = await executeDeployedFunction(- 'fathom-backfill',- buildRoutePayload({ days: 30 }),- );+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'fathom-backfill',+ payload: buildRoutePayload({ days: 30 }),+ });expect(execution.status).toBe('SUCCESS');expect(execution.data).toEqual({@@ -93,12 +59,15 @@ describe('Fathom app deployed functions', () => {});it('rejects invalid workflow action input before looking up a connection', async () => {- const listExecution = await executeDeployedFunction(- 'fathom-list-calls-by-participant',- { participantEmail: ' ' },- );- const syncExecution = await executeDeployedFunction('fathom-sync-call', {- recordingId: '42',+ const listExecution = await executeDeployedFunctionOrThrow({+ functionName: 'fathom-list-calls-by-participant',+ payload: { participantEmail: ' ' },+ });+ const syncExecution = await executeDeployedFunctionOrThrow({+ functionName: 'fathom-sync-call',+ payload: {+ recordingId: '42',+ },});expect(listExecution.status).toBe('SUCCESS');@@ -114,12 +83,15 @@ describe('Fathom app deployed functions', () => {});it('reports the missing Fathom connection from the deployed workflow actions', async () => {- const listExecution = await executeDeployedFunction(- 'fathom-list-calls-by-participant',- { participantEmail: '[email protected]' },- );- const syncExecution = await executeDeployedFunction('fathom-sync-call', {- recordingId: 42,+ const listExecution = await executeDeployedFunctionOrThrow({+ functionName: 'fathom-list-calls-by-participant',+ payload: { participantEmail: '[email protected]' },+ });+ const syncExecution = await executeDeployedFunctionOrThrow({+ functionName: 'fathom-sync-call',+ payload: {+ recordingId: 42,+ },});expect(listExecution.status).toBe('SUCCESS');diff --git a/packages/twenty-apps/public/fathom/src/__tests__/disconnected-media-cleanup.integration-test.ts b/packages/twenty-apps/public/fathom/src/__tests__/disconnected-media-cleanup.integration-test.tsindex e8c0423a022..f51416f74bd 100644--- a/packages/twenty-apps/public/fathom/src/__tests__/disconnected-media-cleanup.integration-test.ts+++ b/packages/twenty-apps/public/fathom/src/__tests__/disconnected-media-cleanup.integration-test.ts@@ -1,7 +1,7 @@import { isNonEmptyString } from '@sniptt/guards';import { randomUUID } from 'node:crypto';import { CoreApiClient } from 'twenty-client-sdk/core';-import { functionExecute } from 'twenty-sdk/cli';+import { executeDeployedFunctionOrThrow } from './execute-deployed-function-or-throw';import { describe, expect, it } from 'vitest';import { createFathomApplicationCoreApiClient } from 'src/__tests__/utils/create-fathom-application-core-api-client.util';@@ -51,18 +51,13 @@ describe('Fathom disconnected media cleanup', () => {});try {- const result = await functionExecute({- appPath: process.cwd(),+ const result = await executeDeployedFunctionOrThrow({functionName: 'fathom-reconcile-media-imports',payload: { disconnectedAccountId: connectedAccountId },});- if (!result.success) {- throw new Error(result.error.message);- }-- expect(result.data.status).toBe('SUCCESS');- expect(result.data.data).toEqual({+ expect(result.status).toBe('SUCCESS');+ expect(result.data).toEqual({candidateCount: 1,updatedRecordingCount: 1,shouldContinue: false,diff --git a/packages/twenty-apps/public/fathom/src/__tests__/execute-deployed-function-or-throw.ts b/packages/twenty-apps/public/fathom/src/__tests__/execute-deployed-function-or-throw.tsnew file mode 100644index 00000000000..7c5a7cccbad--- /dev/null+++ b/packages/twenty-apps/public/fathom/src/__tests__/execute-deployed-function-or-throw.ts@@ -0,0 +1,50 @@+import {+ MetadataApiClient,+ type MetadataSchema,+} from 'twenty-client-sdk/metadata';++import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++export const executeDeployedFunctionOrThrow = async ({+ functionName,+ payload,+}: {+ functionName: string;+ payload: Record<string, unknown>;+}): Promise<+ Omit<MetadataSchema.LogicFunctionExecutionResult, '__typename'>+> => {+ const client = new MetadataApiClient();+ const {+ findOneApplication: application,+ findManyLogicFunctions: logicFunctions,+ } = await client.query({+ findOneApplication: {+ __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },+ id: true,+ },+ findManyLogicFunctions: { id: true, name: true, applicationId: true },+ });+ const matches = logicFunctions.filter(+ (logicFunction) =>+ logicFunction.applicationId === application.id &&+ logicFunction.name === functionName,+ );+ if (matches.length !== 1) {+ throw new Error(+ `Expected one deployed app function named ${functionName}, found ${matches.length}`,+ );+ }++ const { executeOneLogicFunction } = await client.mutation({+ executeOneLogicFunction: {+ __args: { input: { id: matches[0].id, payload } },+ data: true,+ status: true,+ logs: true,+ duration: true,+ error: true,+ },+ });+ return executeOneLogicFunction;+};diff --git a/packages/twenty-apps/public/fathom/src/__tests__/global-setup.ts b/packages/twenty-apps/public/fathom/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/fathom/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/fathom/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/fathom/src/__tests__/read-manifest-logic-function-names-or-throw.ts b/packages/twenty-apps/public/fathom/src/__tests__/read-manifest-logic-function-names-or-throw.tsnew file mode 100644index 00000000000..87ac8e9fb5a--- /dev/null+++ b/packages/twenty-apps/public/fathom/src/__tests__/read-manifest-logic-function-names-or-throw.ts@@ -0,0 +1,23 @@+import { z } from 'zod';++import { runTwenty } from './run-twenty';++const buildResultSchema = z.object({+ manifest: z.object({+ logicFunctions: z.array(z.object({ name: z.string() })),+ }),+});++export const readManifestLogicFunctionNamesOrThrow = async (): Promise<+ string[]+> => {+ const result = await runTwenty(['app', 'build']);++ if (!result.ok) {+ throw new Error(`App build failed: ${JSON.stringify(result.error)}`);+ }++ const { manifest } = buildResultSchema.parse(result.data);++ return manifest.logicFunctions.map((logicFunction) => logicFunction.name);+};diff --git a/packages/twenty-apps/public/fathom/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/fathom/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..3a4908f10f6--- /dev/null+++ b/packages/twenty-apps/public/fathom/src/__tests__/run-twenty.ts@@ -0,0 +1,71 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+ details?: unknown;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/list-calendar-events-in-window.test.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/list-calendar-events-in-window.test.tsnew file mode 100644index 00000000000..a23e43c93dc--- /dev/null+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/list-calendar-events-in-window.test.ts@@ -0,0 +1,43 @@+import { describe, expect, it, vi } from 'vitest';++import { listCalendarEventsInWindow } from 'src/logic-functions/utils/list-calendar-events-in-window.util';++describe('listCalendarEventsInWindow', () => {+ it.each([null, undefined])(+ 'rejects an incomplete candidate with startsAt %s',+ async (startsAt) => {+ const query = vi.fn().mockResolvedValue({+ calendarEvents: {+ edges: [{ node: { id: 'event', startsAt } }],+ pageInfo: { hasNextPage: false },+ },+ });++ await expect(+ listCalendarEventsInWindow({+ coreApiClient: { query },+ earliestStart: '2026-01-01T00:00:00Z',+ latestStart: '2026-01-02T00:00:00Z',+ }),+ ).resolves.toBeUndefined();+ },+ );++ it('keeps a dated event without a conference link', async () => {+ const startsAt = '2026-01-01T12:00:00Z';+ const query = vi.fn().mockResolvedValue({+ calendarEvents: {+ edges: [{ node: { id: 'event', startsAt } }],+ pageInfo: { hasNextPage: false },+ },+ });++ await expect(+ listCalendarEventsInWindow({+ coreApiClient: { query },+ earliestStart: '2026-01-01T00:00:00Z',+ latestStart: '2026-01-02T00:00:00Z',+ }),+ ).resolves.toEqual([{ id: 'event', startsAt, conferenceLink: null }]);+ });+});diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/cleanup-disconnected-fathom-media-imports.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/cleanup-disconnected-fathom-media-imports.util.tsindex 1491094167d..a1063387364 100644--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/cleanup-disconnected-fathom-media-imports.util.ts+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/cleanup-disconnected-fathom-media-imports.util.ts@@ -3,6 +3,7 @@ import { type CoreApiClient } from 'twenty-client-sdk/core';import { isDefined } from 'src/utils/is-defined';import { FATHOM_MEDIA_FAILURE_REASON } from 'src/constants/fathom-media-failure-reason.constant';+import { type FathomRecordingImportReference } from 'src/logic-functions/types/fathom-recording-import-reference.type';import { buildDisconnectedFathomMediaReconciliationPlan } from 'src/logic-functions/utils/build-disconnected-fathom-media-reconciliation-plan.util';import { findDisconnectedFathomMediaImports } from 'src/logic-functions/utils/find-disconnected-fathom-media-imports.util';import { listFathomConnections } from 'src/logic-functions/utils/list-fathom-connections.util';@@ -43,7 +44,11 @@ export const cleanupDisconnectedFathomMediaImports = async ({mediaFailureReason:FATHOM_MEDIA_FAILURE_REASON.CONNECTED_ACCOUNT_UNAVAILABLE,};- const updates = [+ const updates: {+ callRecordings: FathomRecordingImportReference[];+ importData: typeof settledData | typeof clearedImportFields;+ status?: 'COMPLETED' | 'FAILED';+ }[] = [{callRecordings: plan.callRecordingsToSettleAndComplete,importData: settledData,diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/list-calendar-events-in-window.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/list-calendar-events-in-window.util.tsindex 1ff95bc0e4c..3fb9149646d 100644--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/list-calendar-events-in-window.util.ts+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/list-calendar-events-in-window.util.ts@@ -9,7 +9,13 @@ import { type CalendarEventCandidate } from 'src/logic-functions/types/calendar-type CalendarEventsPage = {calendarEvents?: {- edges?: Array<{ node: CalendarEventCandidate }>;+ edges?: Array<{+ node: {+ id: string;+ startsAt?: string | null;+ conferenceLink?: CalendarEventCandidate['conferenceLink'];+ };+ }>;pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };};};@@ -60,9 +66,17 @@ export const listCalendarEventsInWindow = async ({});const pageInfo = queryResult.calendarEvents?.pageInfo;- calendarEvents.push(- ...(queryResult.calendarEvents?.edges ?? []).map((edge) => edge.node),- );+ for (const { node } of queryResult.calendarEvents?.edges ?? []) {+ if (!isNonEmptyString(node.startsAt)) {+ return undefined;+ }++ calendarEvents.push({+ id: node.id,+ startsAt: node.startsAt,+ conferenceLink: node.conferenceLink ?? null,+ });+ }if (pageInfo?.hasNextPage !== true) {return calendarEvents;diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.tsindex 3707d9134c8..e36b14c9e7e 100644--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts@@ -21,7 +21,12 @@ export const upsertCallRecording = async ({try {await coreApiClient.mutation({createCallRecording: {- __args: { data: { id: callRecordingId, ...createFields } },+ __args: {+ data: {+ id: callRecordingId,+ ...createFields,+ },+ },id: true,},});diff --git a/packages/twenty-apps/public/fathom/tsconfig.json b/packages/twenty-apps/public/fathom/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/fathom/tsconfig.json+++ b/packages/twenty-apps/public/fathom/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/fathom/yarn.lock b/packages/twenty-apps/public/fathom/yarn.lockindex 5dec32861dd..d5b8d43dee6 100644--- a/packages/twenty-apps/public/fathom/yarn.lock+++ b/packages/twenty-apps/public/fathom/yarn.lock@@ -933,7 +933,7 @@ __metadata:"@typescript/native-preview": "npm:^7.0.0-dev.20260116.1"fathom-typescript: "npm:0.0.43"oxlint: "npm:^0.16.0"- twenty-client-sdk: "npm:2.38.0"+ twenty-client-sdk: "npm:2.50.0"twenty-sdk: "npm:2.38.0"typescript: "npm:^5.9.3"vite-tsconfig-paths: "npm:^4.2.1"@@ -2822,6 +2822,19 @@ __metadata:languageName: nodelinkType: hard+"twenty-client-sdk@npm:2.50.0":+ version: 2.50.0+ resolution: "twenty-client-sdk@npm:2.50.0"+ dependencies:+ "@genql/runtime": "npm:^2.10.0"+ esbuild: "npm:^0.28.1"+ graphql: "npm:^16.8.1"+ lodash: "npm:^4.17.21"+ prettier: "npm:^3.8.3"+ checksum: 10c0/d1a545e9f986747dcf30efbb37dbf8a6a0da773a2c91ef83cc04cf7c4a90767d7bfbb223dacc293e7f5f8fdcfe431c67690d838ff9553eb24dec0c897d75dd66+ languageName: node+ linkType: hard+"twenty-sdk@npm:2.38.0":version: 2.38.0resolution: "twenty-sdk@npm:2.38.0"diff --git a/packages/twenty-apps/public/fireflies/src/__tests__/global-setup.ts b/packages/twenty-apps/public/fireflies/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/fireflies/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/fireflies/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/fireflies/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/fireflies/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/fireflies/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/fireflies/src/__tests__/twenty-fireflies.integration-test.ts b/packages/twenty-apps/public/fireflies/src/__tests__/twenty-fireflies.integration-test.tsindex 9996562fac9..7f4d9e2db70 100644--- a/packages/twenty-apps/public/fireflies/src/__tests__/twenty-fireflies.integration-test.ts+++ b/packages/twenty-apps/public/fireflies/src/__tests__/twenty-fireflies.integration-test.ts@@ -41,7 +41,7 @@ const getServerCallRecordingStatuses = async (): Promise<string[]> => {if (statusEnum === undefined) {throw new Error(- 'enumCallRecordingStatusEnum is missing from twenty-client-sdk/core; regenerate the client against a running server (yarn twenty dev) before the integration suite',+ 'enumCallRecordingStatusEnum is missing from twenty-client-sdk/core; regenerate the client against a running server (twenty app generate-client) before the integration suite',);}diff --git a/packages/twenty-apps/public/fireflies/tsconfig.json b/packages/twenty-apps/public/fireflies/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/fireflies/tsconfig.json+++ b/packages/twenty-apps/public/fireflies/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/granola/AGENTS.md b/packages/twenty-apps/public/granola/AGENTS.mdindex 6c4207aecb7..0085c869b01 100644--- a/packages/twenty-apps/public/granola/AGENTS.md+++ b/packages/twenty-apps/public/granola/AGENTS.md@@ -48,23 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/granola/CLAUDE.md b/packages/twenty-apps/public/granola/CLAUDE.mdindex 6c4207aecb7..0085c869b01 100644--- a/packages/twenty-apps/public/granola/CLAUDE.md+++ b/packages/twenty-apps/public/granola/CLAUDE.md@@ -48,23 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/granola/SETUP.md b/packages/twenty-apps/public/granola/SETUP.mdindex b34c452e0c8..3d676d5e9fa 100644--- a/packages/twenty-apps/public/granola/SETUP.md+++ b/packages/twenty-apps/public/granola/SETUP.md@@ -25,10 +25,10 @@ yarn install --immutableyarn lintyarn typecheckyarn test:unit-yarn twenty dev:build+twenty app build```-For installation tests, start an isolated Twenty test instance with `yarn twenty docker:start --test`, then run `TWENTY_API_URL=http://localhost:2021 yarn test`. The integration configuration defaults to the scaffold's local dev instance at port 2020; the `--test` instance listens on 2021, hence the override above. Override `TWENTY_API_URL` and `TWENTY_API_KEY` only with credentials for an isolated test workspace: setup installs and teardown uninstalls this app.+Install the standalone CLI with `npm install -g twenty`. For installation tests, start an isolated Twenty instance with Docker or the repository development setup, then set `TWENTY_API_URL` and `TWENTY_API_KEY` for that instance and run `yarn test`. Use a disposable workspace: setup installs and teardown uninstalls this app.The deployed function-execution tests need an authenticated QA user’s access token in `TWENTY_API_KEY`. The scaffold’s default API key can install the app and inspect its schema, but cannot authorize user-only function execution.diff --git a/packages/twenty-apps/public/granola/src/__tests__/deployed-functions.integration-test.ts b/packages/twenty-apps/public/granola/src/__tests__/deployed-functions.integration-test.tsindex 0438c304a18..8080594ddb8 100644--- a/packages/twenty-apps/public/granola/src/__tests__/deployed-functions.integration-test.ts+++ b/packages/twenty-apps/public/granola/src/__tests__/deployed-functions.integration-test.ts@@ -1,37 +1,10 @@-import { readFileSync } from 'node:fs';-import { join } from 'node:path';import { MetadataApiClient } from 'twenty-client-sdk/metadata';-import { functionExecute } from 'twenty-sdk/cli';+import { executeDeployedFunctionOrThrow } from './execute-deployed-function-or-throw';+import { readManifestLogicFunctionNamesOrThrow } from './read-manifest-logic-function-names-or-throw';import { describe, expect, it } from 'vitest';-import { z } from 'zod';import { GRANOLA_BACKFILL_ROUTE_PATH } from 'src/constants/granola-backfill-route-path';-const APP_PATH = process.cwd();-const MANIFEST_SCHEMA = z.object({- logicFunctions: z.array(z.object({ name: z.string() })),-});--const executeDeployedFunction = async ({- functionName,- payload,-}: {- functionName: string;- payload: Record<string, unknown>;-}) => {- const result = await functionExecute({- appPath: APP_PATH,- functionName,- payload,- });- if (!result.success) {- throw new Error(- `Could not execute ${functionName}: ${result.error.message}`,- );- }- return result.data;-};-const buildBackfillRoutePayload = (body: Record<string, unknown>) => ({headers: {},queryStringParameters: {},@@ -45,27 +18,19 @@ const buildBackfillRoutePayload = (body: Record<string, unknown>) => ({describe('Granola deployed functions', () => {it('deploys every function declared by the built application', async () => {- const manifest = MANIFEST_SCHEMA.parse(- JSON.parse(- readFileSync(- join(APP_PATH, '.twenty', 'output', 'manifest.json'),- 'utf8',- ),- ),- );const result = await new MetadataApiClient().query({findManyLogicFunctions: { name: true },});const deployedNames = result.findManyLogicFunctions.map((logicFunction) => logicFunction.name,);- for (const { name } of manifest.logicFunctions) {+ for (const name of await readManifestLogicFunctionNamesOrThrow()) {expect(deployedNames).toContain(name);}});it('reports the missing API key from the deployed connection status route', async () => {- const execution = await executeDeployedFunction({+ const execution = await executeDeployedFunctionOrThrow({functionName: 'granola-connection-status',payload: {},});@@ -76,7 +41,7 @@ describe('Granola deployed functions', () => {it.each([0, -1, 3651, 1.5, '31'])('rejects the invalid backfill window %s before enqueueing',async (days) => {- const execution = await executeDeployedFunction({+ const execution = await executeDeployedFunctionOrThrow({functionName: 'granola-backfill',payload: buildBackfillRoutePayload({ days }),});@@ -114,7 +79,7 @@ describe('Granola deployed functions', () => {])('validates inputs in deployed $functionName',async ({ functionName, payload, error }) => {- const execution = await executeDeployedFunction({+ const execution = await executeDeployedFunctionOrThrow({functionName,payload,});@@ -133,7 +98,7 @@ describe('Granola deployed functions', () => {])('reports the missing key from deployed $functionName',async ({ functionName, payload }) => {- const execution = await executeDeployedFunction({+ const execution = await executeDeployedFunctionOrThrow({functionName,payload,});diff --git a/packages/twenty-apps/public/granola/src/__tests__/execute-deployed-function-or-throw.ts b/packages/twenty-apps/public/granola/src/__tests__/execute-deployed-function-or-throw.tsnew file mode 100644index 00000000000..7c5a7cccbad--- /dev/null+++ b/packages/twenty-apps/public/granola/src/__tests__/execute-deployed-function-or-throw.ts@@ -0,0 +1,50 @@+import {+ MetadataApiClient,+ type MetadataSchema,+} from 'twenty-client-sdk/metadata';++import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++export const executeDeployedFunctionOrThrow = async ({+ functionName,+ payload,+}: {+ functionName: string;+ payload: Record<string, unknown>;+}): Promise<+ Omit<MetadataSchema.LogicFunctionExecutionResult, '__typename'>+> => {+ const client = new MetadataApiClient();+ const {+ findOneApplication: application,+ findManyLogicFunctions: logicFunctions,+ } = await client.query({+ findOneApplication: {+ __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },+ id: true,+ },+ findManyLogicFunctions: { id: true, name: true, applicationId: true },+ });+ const matches = logicFunctions.filter(+ (logicFunction) =>+ logicFunction.applicationId === application.id &&+ logicFunction.name === functionName,+ );+ if (matches.length !== 1) {+ throw new Error(+ `Expected one deployed app function named ${functionName}, found ${matches.length}`,+ );+ }++ const { executeOneLogicFunction } = await client.mutation({+ executeOneLogicFunction: {+ __args: { input: { id: matches[0].id, payload } },+ data: true,+ status: true,+ logs: true,+ duration: true,+ error: true,+ },+ });+ return executeOneLogicFunction;+};diff --git a/packages/twenty-apps/public/granola/src/__tests__/global-setup.ts b/packages/twenty-apps/public/granola/src/__tests__/global-setup.tsindex 9ae73180e9c..7ce43b88ebd 100644--- a/packages/twenty-apps/public/granola/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/granola/src/__tests__/global-setup.ts@@ -1,28 +1,6 @@import { isNonEmptyString } from '@sniptt/guards';-import { isDefined } from 'twenty-sdk/utils';-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');-const TEST_CONFIG_PATH = path.join(CONFIG_DIR, 'config.test.json');-let previousTestConfig: Buffer | undefined;-let isTestConfigWritten = false;--const restoreTestConfig = () => {- if (!isTestConfigWritten) {- return;- }- if (isDefined(previousTestConfig)) {- fs.writeFileSync(TEST_CONFIG_PATH, previousTestConfig);- } else {- fs.rmSync(TEST_CONFIG_PATH, { force: true });- }- isTestConfigWritten = false;-};+import { runTwenty } from './run-twenty';function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;@@ -31,7 +9,6 @@ function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {if (!isNonEmptyString(apiUrl) || !isNonEmptyString(apiKey)) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -40,81 +17,39 @@ function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {}async function checkServerOrThrow(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig({ apiUrl, apiKey }: { apiUrl: string; apiKey: string }) {- const payload = JSON.stringify(- {- remotes: {- local: { apiUrl, apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- previousTestConfig = fs.existsSync(TEST_CONFIG_PATH)- ? fs.readFileSync(TEST_CONFIG_PATH)- : undefined;- fs.writeFileSync(TEST_CONFIG_PATH, payload);- isTestConfigWritten = true;-}-export async function setup() {- const { apiUrl, apiKey } = validateEnvironmentOrThrow();+ const { apiUrl } = validateEnvironmentOrThrow();await checkServerOrThrow(apiUrl);+ await teardown();- writeConfig({ apiUrl, apiKey });-- try {- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {- throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,- );- }- } catch (error) {- restoreTestConfig();- throw error;+ if (!result.ok) {+ throw new Error(+ `App apply failed: ${result.error.code} ${result.error.message}`,+ );}}export async function teardown() {- if (!isTestConfigWritten) {- return;- }- try {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,- );- }- } finally {- restoreTestConfig();+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,+ );}}diff --git a/packages/twenty-apps/public/granola/src/__tests__/read-manifest-logic-function-names-or-throw.ts b/packages/twenty-apps/public/granola/src/__tests__/read-manifest-logic-function-names-or-throw.tsnew file mode 100644index 00000000000..2cf1cf4719f--- /dev/null+++ b/packages/twenty-apps/public/granola/src/__tests__/read-manifest-logic-function-names-or-throw.ts@@ -0,0 +1,23 @@+import { z } from 'zod';++import { runTwenty } from './run-twenty';++const buildResultSchema = z.object({+ manifest: z.object({+ logicFunctions: z.array(z.object({ name: z.string() })),+ }),+});++export const readManifestLogicFunctionNamesOrThrow = async (): Promise<+ string[]+> => {+ const result = await runTwenty(['app', 'build']);++ if (!result.ok) {+ throw new Error(`App build failed: ${result.error.message}`);+ }++ const { manifest } = buildResultSchema.parse(result.data);++ return manifest.logicFunctions.map((logicFunction) => logicFunction.name);+};diff --git a/packages/twenty-apps/public/granola/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/granola/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/granola/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/granola/tsconfig.json b/packages/twenty-apps/public/granola/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/granola/tsconfig.json+++ b/packages/twenty-apps/public/granola/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/last-contact/AGENTS.md b/packages/twenty-apps/public/last-contact/AGENTS.mdindex e6c442eb346..f82c8f78a37 100644--- a/packages/twenty-apps/public/last-contact/AGENTS.md+++ b/packages/twenty-apps/public/last-contact/AGENTS.md@@ -48,19 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/last-contact/CLAUDE.md b/packages/twenty-apps/public/last-contact/CLAUDE.mdindex e6c442eb346..f82c8f78a37 100644--- a/packages/twenty-apps/public/last-contact/CLAUDE.md+++ b/packages/twenty-apps/public/last-contact/CLAUDE.md@@ -48,19 +48,13 @@## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+Use the standalone Twenty CLI to generate supported entities:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |+```bash+twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input+```-This helps automatically generate required IDs etc.+For other entity types, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers. The SDK no longer supplies a CLI.diff --git a/packages/twenty-apps/public/last-contact/src/__tests__/global-setup.ts b/packages/twenty-apps/public/last-contact/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/last-contact/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/last-contact/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/last-contact/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/last-contact/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/last-contact/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/last-contact/src/utils/collect-message-interactions.ts b/packages/twenty-apps/public/last-contact/src/utils/collect-message-interactions.tsindex b07d9db2bc7..c1c644efe11 100644--- a/packages/twenty-apps/public/last-contact/src/utils/collect-message-interactions.ts+++ b/packages/twenty-apps/public/last-contact/src/utils/collect-message-interactions.ts@@ -10,13 +10,6 @@ import { type InteractionDirection } from 'src/utils/update-person-last-contact'const PAGE_SIZE = 200;-const SENDER_OR_TEAM_MEMBER_FILTER = {- or: [- { role: { eq: 'FROM' } },- { workspaceMemberId: { is: 'NOT_NULL' } },- ],-};-export type MessageInteraction = {receivedAt: string;workspaceMemberId: string | null;@@ -45,7 +38,12 @@ const collectSenderAndTeamMemberParticipants = async (filter: {and: [{ messageId: { in: ids } },- SENDER_OR_TEAM_MEMBER_FILTER,+ {+ or: [+ { role: { eq: 'FROM' } },+ { workspaceMemberId: { is: 'NOT_NULL' } },+ ],+ },],},first: PAGE_SIZE,diff --git a/packages/twenty-apps/public/last-contact/tsconfig.json b/packages/twenty-apps/public/last-contact/tsconfig.jsonindex f71645f97ac..0ff094dffe9 100644--- a/packages/twenty-apps/public/last-contact/tsconfig.json+++ b/packages/twenty-apps/public/last-contact/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/linear/src/__tests__/global-setup.ts b/packages/twenty-apps/public/linear/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/linear/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/linear/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/linear/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/linear/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/linear/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/linear/tsconfig.json b/packages/twenty-apps/public/linear/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/linear/tsconfig.json+++ b/packages/twenty-apps/public/linear/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/people-data-labs/src/__tests__/global-setup.ts b/packages/twenty-apps/public/people-data-labs/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/people-data-labs/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/people-data-labs/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/people-data-labs/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/people-data-labs/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/people-data-labs/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/people-data-labs/tsconfig.json b/packages/twenty-apps/public/people-data-labs/tsconfig.jsonindex abacf4dcf6d..58d1334ffb2 100644--- a/packages/twenty-apps/public/people-data-labs/tsconfig.json+++ b/packages/twenty-apps/public/people-data-labs/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/slack/package.json b/packages/twenty-apps/public/slack/package.jsonindex cf8272d5c89..22ddbc58268 100644--- a/packages/twenty-apps/public/slack/package.json+++ b/packages/twenty-apps/public/slack/package.json@@ -46,6 +46,7 @@"twenty-ui": "^1.0.0-alpha.1","typescript": "^5.9.3","vite-tsconfig-paths": "^4.2.1",- "vitest": "^4.0.0"+ "vitest": "^4.0.0",+ "zod": "^4.1.11"}}diff --git a/packages/twenty-apps/public/slack/src/__tests__/README.md b/packages/twenty-apps/public/slack/src/__tests__/README.mdindex 60b904cacd9..51879ed95e5 100644--- a/packages/twenty-apps/public/slack/src/__tests__/README.md+++ b/packages/twenty-apps/public/slack/src/__tests__/README.md@@ -40,7 +40,7 @@ file: `utils/*.util.ts` for behaviour, `types/*.type.ts` for shared shapes,`constants/*.constant.ts` for shared test values.`slack-deployed-functions.integration-test.ts` sits one level further out: it-uses `functionExecute` from `twenty-sdk/cli` to run the functions the way the+uses `executeOneLogicFunction` from the metadata client to run the functions the way theserver runs them - deployed, in the app runtime, with the app's own accesstoken and server variables - and asserts on the returned status, data anderror.diff --git a/packages/twenty-apps/public/slack/src/__tests__/execute-deployed-function-or-throw.ts b/packages/twenty-apps/public/slack/src/__tests__/execute-deployed-function-or-throw.tsnew file mode 100644index 00000000000..7c5a7cccbad--- /dev/null+++ b/packages/twenty-apps/public/slack/src/__tests__/execute-deployed-function-or-throw.ts@@ -0,0 +1,50 @@+import {+ MetadataApiClient,+ type MetadataSchema,+} from 'twenty-client-sdk/metadata';++import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++export const executeDeployedFunctionOrThrow = async ({+ functionName,+ payload,+}: {+ functionName: string;+ payload: Record<string, unknown>;+}): Promise<+ Omit<MetadataSchema.LogicFunctionExecutionResult, '__typename'>+> => {+ const client = new MetadataApiClient();+ const {+ findOneApplication: application,+ findManyLogicFunctions: logicFunctions,+ } = await client.query({+ findOneApplication: {+ __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },+ id: true,+ },+ findManyLogicFunctions: { id: true, name: true, applicationId: true },+ });+ const matches = logicFunctions.filter(+ (logicFunction) =>+ logicFunction.applicationId === application.id &&+ logicFunction.name === functionName,+ );+ if (matches.length !== 1) {+ throw new Error(+ `Expected one deployed app function named ${functionName}, found ${matches.length}`,+ );+ }++ const { executeOneLogicFunction } = await client.mutation({+ executeOneLogicFunction: {+ __args: { input: { id: matches[0].id, payload } },+ data: true,+ status: true,+ logs: true,+ duration: true,+ error: true,+ },+ });+ return executeOneLogicFunction;+};diff --git a/packages/twenty-apps/public/slack/src/__tests__/global-setup.ts b/packages/twenty-apps/public/slack/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/slack/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/slack/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/slack/src/__tests__/read-manifest-logic-function-names-or-throw.ts b/packages/twenty-apps/public/slack/src/__tests__/read-manifest-logic-function-names-or-throw.tsnew file mode 100644index 00000000000..2cf1cf4719f--- /dev/null+++ b/packages/twenty-apps/public/slack/src/__tests__/read-manifest-logic-function-names-or-throw.ts@@ -0,0 +1,23 @@+import { z } from 'zod';++import { runTwenty } from './run-twenty';++const buildResultSchema = z.object({+ manifest: z.object({+ logicFunctions: z.array(z.object({ name: z.string() })),+ }),+});++export const readManifestLogicFunctionNamesOrThrow = async (): Promise<+ string[]+> => {+ const result = await runTwenty(['app', 'build']);++ if (!result.ok) {+ throw new Error(`App build failed: ${result.error.message}`);+ }++ const { manifest } = buildResultSchema.parse(result.data);++ return manifest.logicFunctions.map((logicFunction) => logicFunction.name);+};diff --git a/packages/twenty-apps/public/slack/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/slack/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/slack/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/slack/src/__tests__/slack-deployed-functions.integration-test.ts b/packages/twenty-apps/public/slack/src/__tests__/slack-deployed-functions.integration-test.tsindex 3470c6fcaf1..3ad7cd1f9d8 100644--- a/packages/twenty-apps/public/slack/src/__tests__/slack-deployed-functions.integration-test.ts+++ b/packages/twenty-apps/public/slack/src/__tests__/slack-deployed-functions.integration-test.ts@@ -1,8 +1,6 @@-import * as fs from 'fs';-import * as path from 'path';-import { MetadataApiClient } from 'twenty-client-sdk/metadata';-import { functionExecute } from 'twenty-sdk/cli';+import { executeDeployedFunctionOrThrow } from './execute-deployed-function-or-throw';+import { readManifestLogicFunctionNamesOrThrow } from './read-manifest-logic-function-names-or-throw';import { beforeAll, describe, expect, it } from 'vitest';import { buildSlackAppMentionEventBody } from 'src/__tests__/utils/build-slack-app-mention-event-body.util';@@ -14,38 +12,6 @@ import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identi// These scenarios run the functions the way the server runs them - deployed,// in the app runtime, with the app's own access token and server variables -// which nothing running in the test process can prove on its own.-const APP_PATH = process.cwd();--const executeDeployedFunction = async (- functionName: string,- payload: Record<string, unknown>,-) => {- const result = await functionExecute({- appPath: APP_PATH,- functionName,- payload,- });-- if (!result.success) {- throw new Error(- `Could not execute ${functionName}: ${result.error.message}`,- );- }-- return result.data;-};--const readManifestLogicFunctionNames = (): string[] => {- const manifest = JSON.parse(- fs.readFileSync(- path.join(APP_PATH, '.twenty', 'output', 'manifest.json'),- 'utf8',- ),- ) as { logicFunctions: { name: string }[] };-- return manifest.logicFunctions.map((logicFunction) => logicFunction.name);-};-describe('Slack app deployed functions', () => {const metadataClient = new MetadataApiClient();@@ -83,11 +49,14 @@ describe('Slack app deployed functions', () => {};const verifiesTestWebhookSecret = async (): Promise<boolean> => {- const execution = await executeDeployedFunction('slack-events-resolver', {- ...buildSlackRoutePayload({- type: 'url_verification',- challenge: 'leftover-secret-probe',- }),+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'slack-events-resolver',+ payload: {+ ...buildSlackRoutePayload({+ type: 'url_verification',+ challenge: 'leftover-secret-probe',+ }),+ },});return execution.status === 'SUCCESS';@@ -159,18 +128,21 @@ describe('Slack app deployed functions', () => {(logicFunction: { name: string }) => logicFunction.name,);- for (const manifestFunctionName of readManifestLogicFunctionNames()) {+ for (const manifestFunctionName of await readManifestLogicFunctionNamesOrThrow()) {expect(deployedFunctionNames).toContain(manifestFunctionName);}});it('should answer the Slack url_verification handshake from the deployed events route', async () => {await withTestWebhookSecret(async () => {- const execution = await executeDeployedFunction('slack-events-resolver', {- ...buildSlackRoutePayload({- type: 'url_verification',- challenge: 'deployed-challenge-token',- }),+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'slack-events-resolver',+ payload: {+ ...buildSlackRoutePayload({+ type: 'url_verification',+ challenge: 'deployed-challenge-token',+ }),+ },});expect(execution.status).toBe('SUCCESS');@@ -184,11 +156,14 @@ describe('Slack app deployed functions', () => {it('should reject an unsigned Slack request from the deployed events route', async () => {await withTestWebhookSecret(async () => {- const execution = await executeDeployedFunction('slack-events-resolver', {- ...buildSlackRoutePayload(- { type: 'url_verification', challenge: 'deployed-challenge-token' },- { secret: 'not-the-signing-secret' },- ),+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'slack-events-resolver',+ payload: {+ ...buildSlackRoutePayload(+ { type: 'url_verification', challenge: 'deployed-challenge-token' },+ { secret: 'not-the-signing-secret' },+ ),+ },});expect(execution.status).toBe('ERROR');@@ -203,14 +178,17 @@ describe('Slack app deployed functions', () => {// the scoped read the way the in-process app runtime fake pretends it does.it('should refuse an event from an unclaimed Slack team through the real key value store', async () => {await withTestWebhookSecret(async () => {- const execution = await executeDeployedFunction('slack-events-resolver', {- ...buildSlackRoutePayload(- buildSlackAppMentionEventBody({- channelId: 'C0DEPLOYED',- text: 'hello',- teamId: 'T0UNCLAIMED',- }),- ),+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'slack-events-resolver',+ payload: {+ ...buildSlackRoutePayload(+ buildSlackAppMentionEventBody({+ channelId: 'C0DEPLOYED',+ text: 'hello',+ teamId: 'T0UNCLAIMED',+ }),+ ),+ },});expect(execution.status).toBe('ERROR');@@ -221,7 +199,10 @@ describe('Slack app deployed functions', () => {});it('should report the missing Slack connection from the deployed channel list tool', async () => {- const execution = await executeDeployedFunction('slack-list-channels', {});+ const execution = await executeDeployedFunctionOrThrow({+ functionName: 'slack-list-channels',+ payload: {},+ });expect(execution.status).toBe('SUCCESS');expect(execution.data).toEqual({diff --git a/packages/twenty-apps/public/slack/tsconfig.json b/packages/twenty-apps/public/slack/tsconfig.jsonindex 5063445b1ea..9b4713561fe 100644--- a/packages/twenty-apps/public/slack/tsconfig.json+++ b/packages/twenty-apps/public/slack/tsconfig.json@@ -28,15 +28,11 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-apps/public/slack/yarn.lock b/packages/twenty-apps/public/slack/yarn.lockindex 8d42ea86115..4fb7ef7652a 100644--- a/packages/twenty-apps/public/slack/yarn.lock+++ b/packages/twenty-apps/public/slack/yarn.lock@@ -1481,6 +1481,7 @@ __metadata:typescript: "npm:^5.9.3"vite-tsconfig-paths: "npm:^4.2.1"vitest: "npm:^4.0.0"+ zod: "npm:^4.1.11"languageName: unknownlinkType: softdiff --git a/packages/twenty-apps/public/teams/SETUP.md b/packages/twenty-apps/public/teams/SETUP.mdindex 509ad1f3a7b..9133485d46d 100644--- a/packages/twenty-apps/public/teams/SETUP.md+++ b/packages/twenty-apps/public/teams/SETUP.md@@ -237,9 +237,11 @@ yarn install --immutableyarn lintyarn typecheckyarn test:unit-yarn twenty dev:build+twenty app build```+Install the standalone CLI with `npm install -g twenty`.+Installation tests use a disposable Twenty workspace. Configure`TWENTY_API_URL` and `TWENTY_API_KEY` for that workspace, then run `yarn test`.The test setup installs and uninstalls the application; do not use the shared QAdiff --git a/packages/twenty-apps/public/teams/src/__tests__/global-setup.ts b/packages/twenty-apps/public/teams/src/__tests__/global-setup.tsindex c7f4d000cb4..9426fbbf8b3 100644--- a/packages/twenty-apps/public/teams/src/__tests__/global-setup.ts+++ b/packages/twenty-apps/public/teams/src/__tests__/global-setup.ts@@ -1,20 +1,12 @@-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';+import { runTwenty } from './run-twenty';-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';--const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');--function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -22,67 +14,40 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);}}-function writeConfig(apiUrl: string, apiKey: string) {- const payload = JSON.stringify(- {- version: 1,- remotes: {- local: { apiUrl, apiKey, twentyCLIAccessToken: apiKey },- },- defaultRemote: 'local',- },- null,- 2,- );-- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);-}-export async function setup() {- const { apiUrl, apiKey } = validateEnv();-- await checkServer(apiUrl);+ const { apiUrl } = validateEnvironmentOrThrow();- writeConfig(apiUrl, apiKey);+ await checkServerOrThrow(apiUrl);+ await teardown();- await appUninstall({ appPath: APP_PATH }).catch(() => {});+ const result = await runTwenty(['app', 'apply', '--create']);- const result = await appDevOnce({- appPath: APP_PATH,- onProgress: (message: string) => console.log(`[dev] ${message}`),- });-- if (!result.success) {+ if (!result.ok) {throw new Error(- `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,+ `App apply failed: ${result.error.code} ${result.error.message}`,);}}export async function teardown() {- const uninstallResult = await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!uninstallResult.success) {- console.warn(- `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,);}}diff --git a/packages/twenty-apps/public/teams/src/__tests__/run-twenty.ts b/packages/twenty-apps/public/teams/src/__tests__/run-twenty.tsnew file mode 100644index 00000000000..349de1e101f--- /dev/null+++ b/packages/twenty-apps/public/teams/src/__tests__/run-twenty.ts@@ -0,0 +1,70 @@+import { spawn } from 'child_process';+import { delimiter, join } from 'path';++type TwentyCliError = {+ code: string;+ message: string;+ hint?: string;+};++export type TwentyCliResult =+ | { ok: true; data: unknown }+ | { ok: false; error: TwentyCliError };++function withoutProjectBinaries(pathValue: string) {+ return pathValue+ .split(delimiter)+ .filter(+ (entry) =>+ entry !== process.env.BERRY_BIN_FOLDER &&+ !entry.endsWith(join('node_modules', '.bin')),+ )+ .join(delimiter);+}++export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {+ const executable = process.env.TWENTY_CLI ?? 'twenty';++ return new Promise((resolve, reject) => {+ const child = spawn(executable, [...cliArguments, '--json'], {+ env: {+ ...process.env,+ PATH: withoutProjectBinaries(process.env.PATH ?? ''),+ },+ stdio: ['ignore', 'pipe', 'inherit'],+ });+ let stdout = '';++ child.stdout.setEncoding('utf8');+ child.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ });++ child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }++ reject(+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),+ );+ });++ child.on('close', (exitCode) => {+ try {+ resolve(JSON.parse(stdout));+ } catch {+ reject(+ new Error(+ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ 'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',+ ),+ );+ }+ });+ });+}diff --git a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.test.ts b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.test.tsindex 10d589e1306..ec619a617a6 100644--- a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.test.ts+++ b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.test.ts@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import { findLatestTeamsCallRecordingIdsForCalendarEventsOrThrow } from 'src/features/transcripts/logic-functions/utils/find-latest-teams-call-recording-ids-for-calendar-events-or-throw';-type CallRecordingNode = { id: string; calendarEventId: string | null };+type CallRecordingNode = { id: string; calendarEventId?: string | null };type QueryRequest = {callRecordings: {@@ -40,6 +40,8 @@ describe('findLatestTeamsCallRecordingIdsForCalendarEventsOrThrow', () => {const query = vi.fn(async () =>toConnection({nodes: [+ { id: 'recording-without-event' },+ { id: 'recording-with-null-event', calendarEventId: null },{ id: 'recording-a-latest', calendarEventId: 'event-a' },{ id: 'recording-b-latest', calendarEventId: 'event-b' },{ id: 'recording-a-older', calendarEventId: 'event-a' },diff --git a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-teams-calendar-event-ids-or-throw.test.ts b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-teams-calendar-event-ids-or-throw.test.tsindex c9138014377..00e5d50b197 100644--- a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-teams-calendar-event-ids-or-throw.test.ts+++ b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/__tests__/find-teams-calendar-event-ids-or-throw.test.ts@@ -39,6 +39,51 @@ describe('findTeamsCalendarEventIdsOrThrow', () => {vi.mocked(getTeamsCalendarEventICalUIdOrThrow).mockReset();});+ it('ignores associations without an external ID or calendar event ID', async () => {+ const query = vi.fn().mockResolvedValue({+ calendarChannelEventAssociations: toConnection({+ nodes: [+ { eventExternalId: undefined, calendarEventId: 'unrelated' },+ { eventExternalId: 'external', calendarEventId: undefined },+ { eventExternalId: 'external', calendarEventId: 'calendar-event' },+ ],+ }),+ });++ await expect(+ findTeamsCalendarEventIdsOrThrow({+ accessToken: 'token',+ coreApiClient: { query },+ references: [{ eventExternalId: 'external' }],+ }),+ ).resolves.toEqual(new Map([['external', 'calendar-event']]));+ expect(getTeamsCalendarEventICalUIdOrThrow).not.toHaveBeenCalled();+ });++ it('uses the iCal fallback when an association has no calendar event ID', async () => {+ const query = vi+ .fn()+ .mockResolvedValueOnce({+ calendarChannelEventAssociations: toConnection({+ nodes: [{ eventExternalId: 'external', calendarEventId: null }],+ }),+ })+ .mockResolvedValueOnce({+ calendarEvents: toConnection({+ nodes: [{ id: 'calendar-event', iCalUid: 'ical-uid' }],+ }),+ });++ await expect(+ findTeamsCalendarEventIdsOrThrow({+ accessToken: 'token',+ coreApiClient: { query },+ references: [{ eventExternalId: 'external', iCalUId: 'ical-uid' }],+ }),+ ).resolves.toEqual(new Map([['external', 'calendar-event']]));+ expect(getTeamsCalendarEventICalUIdOrThrow).not.toHaveBeenCalled();+ });+it('should not link a reference whose associations point to different events on different pages', async () => {vi.mocked(getTeamsCalendarEventICalUIdOrThrow).mockResolvedValue('ical-series-master-1',diff --git a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-deleted-and-completed-call-recording-ids-or-throw.ts b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-deleted-and-completed-call-recording-ids-or-throw.tsindex d5d9d3b9b46..e0914ce955d 100644--- a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-deleted-and-completed-call-recording-ids-or-throw.ts+++ b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-deleted-and-completed-call-recording-ids-or-throw.ts@@ -5,7 +5,7 @@ type ExistingCallRecording = {id: string;status: string | null;createdAt: string;- deletedAt: string | null;+ deletedAt?: string | null;};const getCallRecordingIds = (callRecordings: ExistingCallRecording[]) =>diff --git a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.ts b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.tsindex 1b2b9e9b123..d2c445953c7 100644--- a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.ts+++ b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-latest-teams-call-recording-ids-for-calendar-events-or-throw.ts@@ -6,8 +6,8 @@ import { TWENTY_QUERY_MAX_RECORDS } from 'src/features/transcripts/logic-functioimport { chunkIntoBatches } from 'src/features/transcripts/logic-functions/utils/chunk-into-batches';type CallRecordingConnection = {- edges: { node: { id: string; calendarEventId: string | null } }[];- pageInfo: { hasNextPage: boolean; endCursor: string | null };+ edges: { node: { id: string; calendarEventId?: string | null } }[];+ pageInfo: { hasNextPage: boolean; endCursor?: string | null };};const addLatestCallRecordingIdsOrThrow = async ({diff --git a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-teams-calendar-event-ids-or-throw.ts b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-teams-calendar-event-ids-or-throw.tsindex e08e6ac8f2e..ff2f0c8acd9 100644--- a/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-teams-calendar-event-ids-or-throw.ts+++ b/packages/twenty-apps/public/teams/src/features/transcripts/logic-functions/utils/find-teams-calendar-event-ids-or-throw.ts@@ -14,77 +14,34 @@ import { matchTeamsCalendarEventIds } from 'src/features/transcripts/logic-functtype RecordConnection<TNode> = {edges: { node: TNode }[];- pageInfo: { hasNextPage: boolean; endCursor: string | null };-};--const listAllNodesOrThrow = async <TNode>({- coreApiClient,- objectName,- filter,- node,- after,-}: {- coreApiClient: Pick<CoreApiClient, 'query'>;- objectName: 'calendarChannelEventAssociations' | 'calendarEvents';- filter: Record<string, unknown>;- node: Record<keyof TNode, true>;- after?: string;-}): Promise<TNode[]> => {- const result = await coreApiClient.query({- [objectName]: {- __args: {- filter,- first: TWENTY_QUERY_MAX_RECORDS,- ...(isDefined(after) ? { after } : {}),- },- edges: { node },- pageInfo: { hasNextPage: true, endCursor: true },- },- });- const connection: RecordConnection<TNode> | undefined = result[objectName];- const nodes = connection?.edges.map((edge) => edge.node) ?? [];- const endCursor = connection?.pageInfo.endCursor;-- if (!connection?.pageInfo.hasNextPage || !isNonEmptyString(endCursor)) {- return nodes;- }-- return [- ...nodes,- ...(await listAllNodesOrThrow({- coreApiClient,- objectName,- filter,- node,- after: endCursor,- })),- ];+ pageInfo: { hasNextPage: boolean; endCursor?: string | null };};const listAllNodesInBatchesOrThrow = async <TNode>({- coreApiClient,- objectName,values,- buildFilter,- node,+ fetchPage,}: {- coreApiClient: Pick<CoreApiClient, 'query'>;- objectName: 'calendarChannelEventAssociations' | 'calendarEvents';values: string[];- buildFilter: (batch: string[]) => Record<string, unknown>;- node: Record<keyof TNode, true>;+ fetchPage: (options: {+ batch: string[];+ after?: string;+ }) => Promise<RecordConnection<TNode> | undefined>;}): Promise<TNode[]> => {const nodes: TNode[] = [];for (const batch of chunkIntoBatches(values, TWENTY_QUERY_MAX_RECORDS)) {- nodes.push(- ...(await listAllNodesOrThrow<TNode>({- coreApiClient,- objectName,- filter: buildFilter(batch),- node,- })),- );+ let after: string | undefined;++ do {+ const connection = await fetchPage({ batch, after });++ nodes.push(...(connection?.edges.map((edge) => edge.node) ?? []));+ after =+ connection?.pageInfo.hasNextPage &&+ isNonEmptyString(connection.pageInfo.endCursor)+ ? connection.pageInfo.endCursor+ : undefined;+ } while (isDefined(after));}return nodes;@@ -98,13 +55,56 @@ const listCalendarChannelEventAssociationsOrThrow = ({eventExternalIds: string[];}): Promise<CalendarChannelEventAssociation[]> =>listAllNodesInBatchesOrThrow<CalendarChannelEventAssociation>({- coreApiClient,- objectName: 'calendarChannelEventAssociations',values: eventExternalIds,- buildFilter: (eventExternalIdBatch) => ({- eventExternalId: { in: eventExternalIdBatch },- }),- node: { eventExternalId: true, calendarEventId: true },+ fetchPage: async ({ batch, after }) => {+ const result = await coreApiClient.query({+ calendarChannelEventAssociations: {+ __args: {+ filter: { eventExternalId: { in: batch } },+ first: TWENTY_QUERY_MAX_RECORDS,+ ...(isDefined(after) ? { after } : {}),+ },+ edges: { node: { eventExternalId: true, calendarEventId: true } },+ pageInfo: { hasNextPage: true, endCursor: true },+ },+ });++ const connection = result.calendarChannelEventAssociations;++ if (!isDefined(connection)) {+ return undefined;+ }++ return {+ ...connection,+ edges: connection.edges.flatMap(+ ({+ node,+ }: {+ node: {+ eventExternalId?: string | null;+ calendarEventId?: string | null;+ };+ }) => {+ if (+ !isNonEmptyString(node.eventExternalId) ||+ !isNonEmptyString(node.calendarEventId)+ ) {+ return [];+ }++ return [+ {+ node: {+ eventExternalId: node.eventExternalId,+ calendarEventId: node.calendarEventId,+ },+ },+ ];+ },+ ),+ };+ },});const listCalendarEventsByICalUidOrThrow = ({@@ -115,14 +115,34 @@ const listCalendarEventsByICalUidOrThrow = ({iCalUIds: string[];}): Promise<CalendarEvent[]> =>listAllNodesInBatchesOrThrow<CalendarEvent>({- coreApiClient,- objectName: 'calendarEvents',values: iCalUIds,- buildFilter: (iCalUIdBatch) => ({- iCalUid: { in: iCalUIdBatch },- isCanceled: { eq: false },- }),- node: { id: true, iCalUid: true },+ fetchPage: async ({ batch, after }) => {+ const result = await coreApiClient.query({+ calendarEvents: {+ __args: {+ filter: { iCalUid: { in: batch }, isCanceled: { eq: false } },+ first: TWENTY_QUERY_MAX_RECORDS,+ ...(isDefined(after) ? { after } : {}),+ },+ edges: { node: { id: true, iCalUid: true } },+ pageInfo: { hasNextPage: true, endCursor: true },+ },+ });+ const connection = result.calendarEvents;++ if (!isDefined(connection)) {+ return undefined;+ }++ return {+ ...connection,+ edges: connection.edges.map(+ ({ node }: { node: { id: string; iCalUid?: string | null } }) => ({+ node: { id: node.id, iCalUid: node.iCalUid ?? null },+ }),+ ),+ };+ },});const addMissingICalUIdsOrThrow = async ({diff --git a/packages/twenty-apps/public/teams/tsconfig.json b/packages/twenty-apps/public/teams/tsconfig.jsonindex 68ccade0fa7..39f49cac9a6 100644--- a/packages/twenty-apps/public/teams/tsconfig.json+++ b/packages/twenty-apps/public/teams/tsconfig.json@@ -28,16 +28,12 @@}},"exclude": [+ "**/__tests__/**","node_modules","dist","**/*.test.ts","**/*.test.tsx","**/*.spec.ts","**/*.integration-test.ts"- ],- "references": [- {- "path": "./tsconfig.spec.json"- }]}diff --git a/packages/twenty-cli/app-template/AGENTS.md b/packages/twenty-cli/app-template/AGENTS.mdindex de6d6045ef4..ff4acf1dd8d 100644--- a/packages/twenty-cli/app-template/AGENTS.md+++ b/packages/twenty-cli/app-template/AGENTS.md@@ -63,23 +63,13 @@ Read the [front component guide](https://docs.twenty.com/developers/extend/apps/## Best practice-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:+It's highly recommended to create new app entities using `twenty app add`. These are the options:-| Entity type | Command | Generated file |-| -------------------- | ---------------------------------------- | ------------------------------------- |-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |+| Entity type | Command | Generated file |+| --------------- | -------------------------------- | --------------------------------- |+| Object | `twenty app add object` | `src/objects/<name>.ts` |+| Field | `twenty app add field` | `src/fields/<name>.ts` |+| Logic function | `twenty app add logic-function` | `src/logic-functions/<name>.ts` |+| Front component | `twenty app add front-component` | `src/front-components/<name>.tsx` |-This helps automatically generate required IDs etc.+These generators create the required UUID v4 identifiers. For roles, skills, agents, views, navigation items, layouts, commands, and connection providers, use the corresponding `twenty-sdk/define` export and generate UUID v4 identifiers.diff --git a/packages/twenty-cli/app-template/README.md b/packages/twenty-cli/app-template/README.mdindex 0b5463eb0f8..a93ac87314c 100644--- a/packages/twenty-cli/app-template/README.md+++ b/packages/twenty-cli/app-template/README.md@@ -30,5 +30,5 @@ Notable changes are documented in [CHANGELOG.md](CHANGELOG.md).## Learn more- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)-- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)+- [Twenty CLI reference](https://docs.twenty.com/developers/extend/apps/operations/cli)- [Discord](https://discord.gg/cx5n4Jzs57)diff --git a/packages/twenty-cli/app-template/SETUP.md b/packages/twenty-cli/app-template/SETUP.mdindex c7a92a07d36..d2e6aa54a08 100644--- a/packages/twenty-cli/app-template/SETUP.md+++ b/packages/twenty-cli/app-template/SETUP.md@@ -1,47 +1,27 @@# Setup-Follow these steps to get your app running locally.+Use Node.js from `.nvmrc` and Yarn 4. Install the standalone CLI globally:-## Prerequisites+```bash+npm install -g twenty+yarn install+```-- Node.js (version specified in `.nvmrc`)-- Yarn 4-- Docker (to run the local Twenty server)+Connect to your existing Twenty workspace, or start a server using the [local-server guide](https://docs.twenty.com/developers/extend/apps/getting-started/local-server):-## Steps+```bash+twenty auth login --url https://your-workspace.twenty.com --name dev+twenty app apply --create+twenty app dev+```-1. Install dependencies:+The first apply registers and installs your app. Dev watches and syncs later source changes. `twenty app init` does not authenticate, start containers, or install the app.- ```bash- yarn install- ```+## Validation- The committed `yarn.lock` pins exact, integrity-checked versions, so this- resolves nothing from the registry.+- `yarn lint`, lint the project.+- `yarn typecheck`, check source and test types.+- `yarn test:unit`, run unit tests.+- `yarn test`, run integration tests against a disposable workspace configured with `TWENTY_API_URL` and `TWENTY_API_KEY`.-2. Start the local Twenty server:-- ```bash- yarn twenty docker:start- ```-- Check the server status at any time with `yarn twenty docker:status`.--3. Start the development server and sync your app:-- ```bash- yarn twenty dev- ```--4. Open [http://localhost:2020](http://localhost:2020) and log in with the default development credentials: `[email protected]` / `[email protected]`.--## Verifying your setup--- `yarn lint` - Lint the project with oxlint-- `yarn typecheck` - Type-check the project-- `yarn test:unit` - Run unit tests-- `yarn test` - Run integration tests--## Troubleshooting--See the [troubleshooting guide](https://docs.twenty.com/developers/extend/apps/getting-started/troubleshooting) or ask on [Discord](https://discord.gg/cx5n4Jzs57).+Integration tests install and uninstall the app. Install the CLI globally or set `TWENTY_CLI` to a local executable path.diff --git a/packages/twenty-cli/app-template/github/workflows/cd.yml b/packages/twenty-cli/app-template/github/workflows/cd.ymlindex 0ec483fc577..247af6704bb 100644--- a/packages/twenty-cli/app-template/github/workflows/cd.yml+++ b/packages/twenty-cli/app-template/github/workflows/cd.yml@@ -32,11 +32,13 @@ jobs:- name: Deployuses: twentyhq/twenty/.github/actions/deploy-twenty-app@mainwith:+ cli-version: CLI-VERSION-TO-BE-GENERATEDapi-url: ${{ env.TWENTY_DEPLOY_URL }}api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}- name: Installuses: twentyhq/twenty/.github/actions/install-twenty-app@mainwith:+ cli-version: CLI-VERSION-TO-BE-GENERATEDapi-url: ${{ env.TWENTY_DEPLOY_URL }}api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}diff --git a/packages/twenty-cli/app-template/github/workflows/publish.yml b/packages/twenty-cli/app-template/github/workflows/publish.ymlindex f6b564bee8e..0938c2cb758 100644--- a/packages/twenty-cli/app-template/github/workflows/publish.yml+++ b/packages/twenty-cli/app-template/github/workflows/publish.yml@@ -41,6 +41,9 @@ jobs:# Trusted publishing requires npm 11.5.1 or later.run: npm install -g npm@latest+ - name: Install Twenty CLI+ run: npm install -g twenty@CLI-VERSION-TO-BE-GENERATED+- name: Install dependenciesrun: yarn install --immutable@@ -49,4 +52,4 @@ jobs:# OIDC provenance for private repos# env:# TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'- run: yarn twenty app:publish+ run: twenty app publishdiff --git a/packages/twenty-cli/app-template/src/__tests__/global-setup.ts b/packages/twenty-cli/app-template/src/__tests__/global-setup.tsindex abc8acab503..9426fbbf8b3 100644--- a/packages/twenty-cli/app-template/src/__tests__/global-setup.ts+++ b/packages/twenty-cli/app-template/src/__tests__/global-setup.ts@@ -1,13 +1,12 @@import { runTwenty } from './run-twenty';-function validateEnv(): { apiUrl: string; apiKey: string } {+function validateEnvironmentOrThrow(): { apiUrl: string; apiKey: string } {const apiUrl = process.env.TWENTY_API_URL;const apiKey = process.env.TWENTY_API_KEY;if (!apiUrl || !apiKey) {throw new Error('TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +- 'Start a local server: yarn twenty docker:start\n' +'Or set them in vitest env config.',);}@@ -15,17 +14,13 @@ function validateEnv(): { apiUrl: string; apiKey: string } {return { apiUrl, apiKey };}-async function checkServer(apiUrl: string) {- let response: Response;-- try {- response = await fetch(`${apiUrl}/healthz`);- } catch {+async function checkServerOrThrow(apiUrl: string) {+ const response = await fetch(`${apiUrl}/healthz`).catch(() => {throw new Error(`Twenty server is not reachable at ${apiUrl}. ` +'Make sure the server is running before executing integration tests.',);- }+ });if (!response.ok) {throw new Error(`Server at ${apiUrl} returned ${response.status}`);@@ -33,10 +28,10 @@ async function checkServer(apiUrl: string) {}export async function setup() {- const { apiUrl } = validateEnv();+ const { apiUrl } = validateEnvironmentOrThrow();- await checkServer(apiUrl);- await runTwenty(['app', 'uninstall', '--yes']);+ await checkServerOrThrow(apiUrl);+ await teardown();const result = await runTwenty(['app', 'apply', '--create']);@@ -50,7 +45,9 @@ export async function setup() {export async function teardown() {const result = await runTwenty(['app', 'uninstall', '--yes']);- if (!result.ok) {- console.warn(`App uninstall failed: ${result.error.message}`);+ if (!result.ok && result.error.code !== 'APP_NOT_INSTALLED') {+ throw new Error(+ `App uninstall failed: ${result.error.code} ${result.error.message}`,+ );}}diff --git a/packages/twenty-cli/app-template/src/__tests__/run-twenty.ts b/packages/twenty-cli/app-template/src/__tests__/run-twenty.tsindex 9a9ffeb7650..349de1e101f 100644--- a/packages/twenty-cli/app-template/src/__tests__/run-twenty.ts+++ b/packages/twenty-cli/app-template/src/__tests__/run-twenty.ts@@ -22,11 +22,11 @@ function withoutProjectBinaries(pathValue: string) {.join(delimiter);}-export function runTwenty(args: string[]): Promise<TwentyCliResult> {+export function runTwenty(cliArguments: string[]): Promise<TwentyCliResult> {const executable = process.env.TWENTY_CLI ?? 'twenty';return new Promise((resolve, reject) => {- const child = spawn(executable, [...args, '--json'], {+ const child = spawn(executable, [...cliArguments, '--json'], {env: {...process.env,PATH: withoutProjectBinaries(process.env.PATH ?? ''),@@ -41,12 +41,16 @@ export function runTwenty(args: string[]): Promise<TwentyCliResult> {});child.on('error', (error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') {+ reject(error);++ return;+ }+reject(- error.code === 'ENOENT'- ? new Error(- `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,- )- : error,+ new Error(+ `${executable} was not found. Install the Twenty CLI globally, or set TWENTY_CLI to its path.`,+ ),);});@@ -56,7 +60,7 @@ export function runTwenty(args: string[]): Promise<TwentyCliResult> {} catch {reject(new Error(- `${executable} ${args.join(' ')} exited with code ${exitCode} without a JSON result. ` ++ `${executable} ${cliArguments.join(' ')} exited with code ${exitCode} without a JSON result. ` +'Check that it is the Twenty CLI (twenty --version), or set TWENTY_CLI to its path.',),);diff --git a/packages/twenty-cli/src/app/__tests__/app-template-global-setup.spec.ts b/packages/twenty-cli/src/app/__tests__/app-template-global-setup.spec.tsnew file mode 100644index 00000000000..0abda3c38ce--- /dev/null+++ b/packages/twenty-cli/src/app/__tests__/app-template-global-setup.spec.ts@@ -0,0 +1,91 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++import {+ setup,+ teardown,+} from '../../../app-template/src/__tests__/global-setup';+import { runTwenty } from '../../../app-template/src/__tests__/run-twenty';++vi.mock('../../../app-template/src/__tests__/run-twenty', () => ({+ runTwenty: vi.fn(),+}));++const notInstalled = {+ ok: false,+ error: { code: 'APP_NOT_INSTALLED', message: 'Not installed.' },+} as const;++const uninstallFailed = {+ ok: false,+ error: { code: 'PERMISSION_DENIED', message: 'Cannot uninstall.' },+} as const;++describe('app template integration setup', () => {+ beforeEach(() => {+ vi.mocked(runTwenty).mockReset();+ vi.stubEnv('TWENTY_API_URL', 'http://localhost:2020');+ vi.stubEnv('TWENTY_API_KEY', 'test-key');+ vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true }));+ });++ afterEach(() => {+ vi.unstubAllEnvs();+ vi.unstubAllGlobals();+ });++ it('installs the app when there is no previous installation to clean up', async () => {+ vi.mocked(runTwenty)+ .mockResolvedValueOnce(notInstalled)+ .mockResolvedValueOnce({ ok: true, data: {} });++ await setup();++ expect(runTwenty).toHaveBeenNthCalledWith(1, ['app', 'uninstall', '--yes']);+ expect(runTwenty).toHaveBeenNthCalledWith(2, ['app', 'apply', '--create']);+ });++ it('reports an unreachable server before running app commands', async () => {+ vi.mocked(fetch).mockRejectedValue(new Error('Connection refused'));++ await expect(setup()).rejects.toThrow(+ 'Twenty server is not reachable at http://localhost:2020.',+ );+ expect(runTwenty).not.toHaveBeenCalled();+ });++ it('preserves HTTP health-check failures before running app commands', async () => {+ vi.mocked(fetch).mockResolvedValue(new Response(null, { status: 503 }));++ await expect(setup()).rejects.toThrow(+ 'Server at http://localhost:2020 returned 503',+ );+ expect(runTwenty).not.toHaveBeenCalled();+ });++ it('does not apply the app when cleanup fails', async () => {+ vi.mocked(runTwenty).mockResolvedValue(uninstallFailed);++ await expect(setup()).rejects.toThrow(+ 'PERMISSION_DENIED Cannot uninstall.',+ );+ expect(runTwenty).toHaveBeenCalledExactlyOnceWith([+ 'app',+ 'uninstall',+ '--yes',+ ]);+ });++ it('surfaces uninstall failures during teardown', async () => {+ vi.mocked(runTwenty).mockResolvedValue(uninstallFailed);++ await expect(teardown()).rejects.toThrow(+ 'PERMISSION_DENIED Cannot uninstall.',+ );+ });++ it('allows teardown after the app was already uninstalled', async () => {+ vi.mocked(runTwenty).mockResolvedValue(notInstalled);++ await expect(teardown()).resolves.toBeUndefined();+ });+});diff --git a/packages/twenty-cli/src/app/__tests__/utils/sorted-glob-plugin.ts b/packages/twenty-cli/src/app/__tests__/utils/sorted-glob-plugin.tsdeleted file mode 100644index f1b3f508cef..00000000000--- a/packages/twenty-cli/src/app/__tests__/utils/sorted-glob-plugin.ts+++ /dev/null@@ -1,19 +0,0 @@-import { type Plugin } from 'esbuild';--const SORTED_GLOB_NAMESPACE = 'sorted-tinyglobby';--export const SORTED_GLOB_PLUGIN: Plugin = {- name: SORTED_GLOB_NAMESPACE,- setup(build) {- build.onResolve({ filter: /^tinyglobby$/ }, (args) =>- args.namespace === SORTED_GLOB_NAMESPACE- ? { path: 'tinyglobby', external: true }- : { path: 'tinyglobby', namespace: SORTED_GLOB_NAMESPACE },- );- build.onLoad({ filter: /.*/, namespace: SORTED_GLOB_NAMESPACE }, () => ({- contents: `const tinyglobby = require('tinyglobby');-module.exports = { ...tinyglobby, glob: async (...args) => (await tinyglobby.glob(...args)).sort() };`,- loader: 'js',- }));- },-};diff --git a/packages/twenty-cli/src/app/add/__tests__/__snapshots__/entity-templates.spec.ts.snap b/packages/twenty-cli/src/app/add/__tests__/__snapshots__/entity-templates.spec.ts.snapnew file mode 100644index 00000000000..91d3ea5974f--- /dev/null+++ b/packages/twenty-cli/src/app/add/__tests__/__snapshots__/entity-templates.spec.ts.snap@@ -0,0 +1,639 @@+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html++exports[`app add templates > preserves runtime templates and filename normalization for HTTPClient2 1`] = `"http-client-2"`;++exports[`app add templates > preserves runtime templates and filename normalization for HTTPClient2 2`] = `+"import { defineLogicFunction } from 'twenty-sdk/define';++// Logic function handler - rename and implement your logic+const handler = async (params: {+ a: string;+ b: number;+}): Promise<{ message: string }> => {+ const { a, b } = params;++ // Replace with your own logic+ const message = \`Hello, input: \${a} and \${b}\`;++ return { message };+};++export default defineLogicFunction({+ universalIdentifier: 'UUID_0',+ name: 'http-client-2',+ description: 'Add a description for your logic function',+ timeoutSeconds: 5,+ handler,+ // Add your trigger here+ // Route trigger example:+ // httpRouteTriggerSettings: {+ // path: '/http-client-2',+ // httpMethod: 'POST',+ // isAuthRequired: true,+ // },+ // Cron trigger example:+ // cronTriggerSettings: {+ // pattern: '0 0 * * *', // Daily at midnight+ // },+ // Database event trigger example:+ // databaseEventTriggerSettings: {+ // eventName: 'objectName.created',+ // // Optional: receive one call per batch of events instead of one per event,+ // // the handler payload then becomes { ...eventInfo, events: [...] }+ // batchMode: true,+ // },+});+"+`;++exports[`app add templates > preserves runtime templates and filename normalization for HTTPClient2 3`] = `+"import { defineFrontComponent } from 'twenty-sdk/define';++// React component - implement your UI here+const Component = () => {+ return (+ <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>+ <h1>My new component!</h1>+ <p>This is your front component: http-client-2</p>+ </div>+ );+};++export default defineFrontComponent({+ universalIdentifier: 'UUID_0',+ name: 'http-client-2',+ description: 'Add a description for your front component',+ component: Component,+});+"+`;++exports[`app add templates > preserves runtime templates and filename normalization for SendInvoice 1`] = `"send-invoice"`;++exports[`app add templates > preserves runtime templates and filename normalization for SendInvoice 2`] = `+"import { defineLogicFunction } from 'twenty-sdk/define';++// Logic function handler - rename and implement your logic+const handler = async (params: {+ a: string;+ b: number;+}): Promise<{ message: string }> => {+ const { a, b } = params;++ // Replace with your own logic+ const message = \`Hello, input: \${a} and \${b}\`;++ return { message };+};++export default defineLogicFunction({+ universalIdentifier: 'UUID_0',+ name: 'send-invoice',+ description: 'Add a description for your logic function',+ timeoutSeconds: 5,+ handler,+ // Add your trigger here+ // Route trigger example:+ // httpRouteTriggerSettings: {+ // path: '/send-invoice',+ // httpMethod: 'POST',+ // isAuthRequired: true,+ // },+ // Cron trigger example:+ // cronTriggerSettings: {+ // pattern: '0 0 * * *', // Daily at midnight+ // },+ // Database event trigger example:+ // databaseEventTriggerSettings: {+ // eventName: 'objectName.created',+ // // Optional: receive one call per batch of events instead of one per event,+ // // the handler payload then becomes { ...eventInfo, events: [...] }+ // batchMode: true,+ // },+});+"+`;++exports[`app add templates > preserves runtime templates and filename normalization for SendInvoice 3`] = `+"import { defineFrontComponent } from 'twenty-sdk/define';++// React component - implement your UI here+const Component = () => {+ return (+ <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>+ <h1>My new component!</h1>+ <p>This is your front component: send-invoice</p>+ </div>+ );+};++export default defineFrontComponent({+ universalIdentifier: 'UUID_0',+ name: 'send-invoice',+ description: 'Add a description for your front component',+ component: Component,+});+"+`;++exports[`app add templates > preserves runtime templates and filename normalization for hello world 1`] = `"hello-world"`;++exports[`app add templates > preserves runtime templates and filename normalization for hello world 2`] = `+"import { defineLogicFunction } from 'twenty-sdk/define';++// Logic function handler - rename and implement your logic+const handler = async (params: {+ a: string;+ b: number;+}): Promise<{ message: string }> => {+ const { a, b } = params;++ // Replace with your own logic+ const message = \`Hello, input: \${a} and \${b}\`;++ return { message };+};++export default defineLogicFunction({+ universalIdentifier: 'UUID_0',+ name: 'hello-world',+ description: 'Add a description for your logic function',+ timeoutSeconds: 5,+ handler,+ // Add your trigger here+ // Route trigger example:+ // httpRouteTriggerSettings: {+ // path: '/hello-world',+ // httpMethod: 'POST',+ // isAuthRequired: true,+ // },+ // Cron trigger example:+ // cronTriggerSettings: {+ // pattern: '0 0 * * *', // Daily at midnight+ // },+ // Database event trigger example:+ // databaseEventTriggerSettings: {+ // eventName: 'objectName.created',+ // // Optional: receive one call per batch of events instead of one per event,+ // // the handler payload then becomes { ...eventInfo, events: [...] }+ // batchMode: true,+ // },+});+"+`;++exports[`app add templates > preserves runtime templates and filename normalization for hello world 3`] = `+"import { defineFrontComponent } from 'twenty-sdk/define';++// React component - implement your UI here+const Component = () => {+ return (+ <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>+ <h1>My new component!</h1>+ <p>This is your front component: hello-world</p>+ </div>+ );+};++export default defineFrontComponent({+ universalIdentifier: 'UUID_0',+ name: 'hello-world',+ description: 'Add a description for your front component',+ component: Component,+});+"+`;++exports[`app add templates > preserves the ACTOR field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.ACTOR,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the ADDRESS field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.ADDRESS,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the ARRAY field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.ARRAY,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the BOOLEAN field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.BOOLEAN,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the CURRENCY field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.CURRENCY,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the DATE field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.DATE,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the DATE_TIME field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.DATE_TIME,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the EMAILS field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.EMAILS,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the FILES field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.FILES,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the FULL_NAME field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.FULL_NAME,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the LINKS field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.LINKS,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the MORPH_RELATION field template 1`] = `+"import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.MORPH_RELATION,+ objectUniversalIdentifier: 'UUID_1',+ relationTargetObjectMetadataUniversalIdentifier: 'UUID_2',+ relationTargetFieldMetadataUniversalIdentifier: 'UUID_3',+ universalSettings: { relationType: RelationType.ONE_TO_MANY, onDelete: OnDeleteAction.CASCADE },+ morphId: 'UUID_4',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the MULTI_SELECT field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.MULTI_SELECT,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the NUMBER field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.NUMBER,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the NUMERIC field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.NUMERIC,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the PHONES field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.PHONES,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the POSITION field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.POSITION,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the RATING field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.RATING,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the RAW_JSON field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.RAW_JSON,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the RELATION field template 1`] = `+"import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.RELATION,+ objectUniversalIdentifier: 'UUID_1',+ relationTargetObjectMetadataUniversalIdentifier: 'UUID_2',+ relationTargetFieldMetadataUniversalIdentifier: 'UUID_3',+ universalSettings: { relationType: RelationType.ONE_TO_MANY, onDelete: OnDeleteAction.CASCADE },+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the RICH_TEXT field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.RICH_TEXT,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the SELECT field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.SELECT,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the TEXT field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.TEXT,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the TS_VECTOR field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.TS_VECTOR,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the UUID field template 1`] = `+"import { defineField, FieldType } from 'twenty-sdk/define';++export default defineField({+ universalIdentifier: 'UUID_0',+ name: 'value',+ label: 'Value',+ type: FieldType.UUID,+ objectUniversalIdentifier: 'UUID_1',+ description: 'A value',+});+"+`;++exports[`app add templates > preserves the object template and its shared name-field identifier 1`] = `+"import { defineObject, FieldType } from 'twenty-sdk/define';++export const NAME_FIELD_UNIVERSAL_IDENTIFIER =+ 'UUID_0';++export default defineObject({+ universalIdentifier: 'UUID_1',+ nameSingular: 'invoice',+ namePlural: 'invoices',+ labelSingular: 'Invoice',+ labelPlural: 'Invoices',+ icon: 'IconBox',+ labelIdentifierFieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,+ fields: [+ {+ universalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,+ type: FieldType.TEXT,+ name: 'name',+ label: 'Name',+ description: 'Name of the invoice',+ icon: 'IconAbc',+ },+ ],+});+"+`;++exports[`app add templates > preserves the record page layout and its fields view reference 1`] = `+"import { definePageLayout, PageLayoutTabLayoutMode, PageLayoutType } from 'twenty-sdk/define';++export default definePageLayout({+ universalIdentifier: 'UUID_0',+ name: 'Default Invoice Layout',+ type: PageLayoutType.RECORD_PAGE,+ objectUniversalIdentifier: 'UUID_1',+ tabs: [+ {+ universalIdentifier: 'UUID_2',+ title: 'Home',+ position: 10,+ icon: 'IconHome',+ layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,+ widgets: [+ {+ universalIdentifier: 'UUID_3',+ title: 'Fields',+ type: 'FIELDS',+ configuration: {+ configurationType: 'FIELDS',+ viewUniversalIdentifier: 'UUID_4',+ },+ },+ ],+ },+ {+ universalIdentifier: 'UUID_5',+ title: 'Timeline',+ position: 20,+ icon: 'IconTimelineEvent',+ layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,+ widgets: [+ {+ universalIdentifier: 'UUID_6',+ title: 'Timeline',+ type: 'TIMELINE',+ configuration: {+ configurationType: 'TIMELINE',+ },+ },+ ],+ },+ ],+});+"+`;diff --git a/packages/twenty-cli/src/app/add/__tests__/add-template-parity.spec.ts b/packages/twenty-cli/src/app/add/__tests__/entity-templates.spec.tssimilarity index 55%rename from packages/twenty-cli/src/app/add/__tests__/add-template-parity.spec.tsrename to packages/twenty-cli/src/app/add/__tests__/entity-templates.spec.tsindex af53168e276..45276e4c66d 100644--- a/packages/twenty-cli/src/app/add/__tests__/add-template-parity.spec.ts+++ b/packages/twenty-cli/src/app/add/__tests__/entity-templates.spec.ts@@ -1,16 +1,10 @@-import { mkdtemp, rm, symlink } from 'node:fs/promises';-import { createRequire } from 'node:module';-import { tmpdir } from 'node:os';-import { join } from 'node:path';-import { fileURLToPath } from 'node:url';-import { build } from 'esbuild';import {FieldMetadataType,RelationOnDeleteAction,RelationType,} from 'twenty-shared/types';-import { afterAll, beforeAll, describe, expect, it } from 'vitest';+import { describe, expect, it } from 'vitest';import { getFieldBaseFile } from '@/app/add/entity-field-template';import { getFrontComponentBaseFile } from '@/app/add/entity-front-component-template';@@ -19,9 +13,6 @@ import { getRecordPageLayoutBaseFile } from '@/app/add/entity-record-page-layoutimport { getObjectBaseFile } from '@/app/add/entity-object-template';import { kebabCase } from '@/app/pull/kebab-case';-const REPOSITORY_ROOT = fileURLToPath(- new URL('../../../../../../', import.meta.url),-);const UUID_PATTERN =/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/g;const normalizeIdentifiers = (content: string) => {@@ -35,60 +26,7 @@ const normalizeIdentifiers = (content: string) => {});};-type SdkReference = {- getFieldBaseFile: typeof getFieldBaseFile;- getFrontComponentBaseFile: typeof getFrontComponentBaseFile;- getLogicFunctionBaseFile: typeof getLogicFunctionBaseFile;- getObjectBaseFile: typeof getObjectBaseFile;- getRecordPageLayoutBaseFile: typeof getRecordPageLayoutBaseFile;- kebabCase: typeof kebabCase;-};--describe('app add template parity with the repository SDK', () => {- let root: string;- let sdk: SdkReference;-- beforeAll(async () => {- root = await mkdtemp(join(tmpdir(), 'twenty-add-parity-'));- await symlink(- join(REPOSITORY_ROOT, 'node_modules'),- join(root, 'node_modules'),- );- const sdkSource = join(REPOSITORY_ROOT, 'packages/twenty-sdk/src');- const oraclePath = join(root, 'sdk.cjs');-- await build({- stdin: {- contents: [- ...[- 'object',- 'field',- 'logic-function',- 'front-component',- 'record-page-layout',- ].map(- (entity) =>- `export * from './cli/utilities/entity/entity-${entity}-template';`,- ),- "export * from './cli/utilities/string/kebab-case';",- ].join('\n'),- resolveDir: sdkSource,- },- outfile: oraclePath,- alias: { '@': sdkSource },- bundle: true,- packages: 'external',- platform: 'node',- format: 'cjs',- target: 'node24',- });- sdk = createRequire(import.meta.url)(oraclePath) as SdkReference;- });-- afterAll(async () => {- await rm(root, { recursive: true, force: true });- });-+describe('app add templates', () => {it('preserves the object template and its shared name-field identifier', () => {const input = {name: 'invoice',@@ -100,21 +38,19 @@ describe('app add template parity with the repository SDK', () => {},};- expect(normalizeIdentifiers(getObjectBaseFile(input))).toBe(- normalizeIdentifiers(sdk.getObjectBaseFile(input)),- );+ expect(normalizeIdentifiers(getObjectBaseFile(input))).toMatchSnapshot();});- it('preserves the SDK record page layout and its fields view reference', () => {+ it('preserves the record page layout and its fields view reference', () => {const input = {objectLabelSingular: 'Invoice',objectUniversalIdentifier: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',fieldsWidgetViewUniversalIdentifier:'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb',};- expect(normalizeIdentifiers(getRecordPageLayoutBaseFile(input))).toBe(- normalizeIdentifiers(sdk.getRecordPageLayoutBaseFile(input)),- );+ expect(+ normalizeIdentifiers(getRecordPageLayoutBaseFile(input)),+ ).toMatchSnapshot();});it.each(Object.values(FieldMetadataType))(@@ -137,22 +73,20 @@ describe('app add template parity with the repository SDK', () => {},};- expect(normalizeIdentifiers(getFieldBaseFile(input))).toBe(- normalizeIdentifiers(sdk.getFieldBaseFile(input)),- );+ expect(normalizeIdentifiers(getFieldBaseFile(input))).toMatchSnapshot();},);it.each(['SendInvoice', 'hello world', 'HTTPClient2'])(- 'preserves runtime templates and SDK filename normalization for %s',+ 'preserves runtime templates and filename normalization for %s',(name) => {- expect(kebabCase(name)).toBe(sdk.kebabCase(name));- expect(normalizeIdentifiers(getLogicFunctionBaseFile({ name }))).toBe(- normalizeIdentifiers(sdk.getLogicFunctionBaseFile({ name })),- );- expect(normalizeIdentifiers(getFrontComponentBaseFile({ name }))).toBe(- normalizeIdentifiers(sdk.getFrontComponentBaseFile({ name })),- );+ expect(kebabCase(name)).toMatchSnapshot();+ expect(+ normalizeIdentifiers(getLogicFunctionBaseFile({ name })),+ ).toMatchSnapshot();+ expect(+ normalizeIdentifiers(getFrontComponentBaseFile({ name })),+ ).toMatchSnapshot();},);diff --git a/packages/twenty-cli/src/app/client/__tests__/generate-application-client.spec.ts b/packages/twenty-cli/src/app/client/__tests__/generate-application-client.spec.tsindex 8bcefca77b9..cfa2db5ed2f 100644--- a/packages/twenty-cli/src/app/client/__tests__/generate-application-client.spec.ts+++ b/packages/twenty-cli/src/app/client/__tests__/generate-application-client.spec.ts@@ -12,7 +12,7 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import { fileURLToPath } from 'node:url';-import { build, stop } from 'esbuild';+import { stop } from 'esbuild';import {afterAll,afterEach,@@ -44,7 +44,6 @@ describe('CLI client generation uses the app generator', () => {let root: string;let appPath: string;let packageRoot: string;- let sdkEntryPath: string;const readGeneratedClient = async () => {const directory = join(packageRoot, 'dist/core/generated');@@ -105,24 +104,6 @@ describe('CLI client generation uses the app generator', () => {join(root, 'node_modules', name),);}- const sdkSource = join(REPOSITORY_ROOT, 'packages/twenty-sdk/src');- sdkEntryPath = join(root, 'sdk-reference.cjs');- await build({- stdin: {- contents: `export { generateApplicationClient } from './application-build/generate-application-client';`,- resolveDir: sdkSource,- },- outfile: sdkEntryPath,- alias: { '@': sdkSource },- bundle: true,- packages: 'external',- platform: 'node',- format: 'cjs',- target: 'node24',- });- await buildTestAppWorker(join(root, 'reference'), {- aliases: { '@/app/client/generate-application-client': sdkEntryPath },- });await buildTestAppWorker(join(root, 'cli'));launch.modulePath = join(root, 'cli/app-worker.cjs');}, 60000);@@ -146,10 +127,8 @@ describe('CLI client generation uses the app generator', () => {await rm(appPath, { recursive: true, force: true });});- it('matches SDK-generated source and bundles byte for byte without an application SDK', async () => {- launch.modulePath = join(root, 'reference/app-worker.cjs');+ it('generates repeatable source and loadable bundles without an application SDK', async () => {const result = await runGeneration();- launch.modulePath = join(root, 'cli/app-worker.cjs');expect(result).toEqual({success: true,data: null,diff --git a/packages/twenty-cli/src/app/manifest/README.md b/packages/twenty-cli/src/app/manifest/README.mdindex 54b118e7b2e..e0fe9fd1e8d 100644--- a/packages/twenty-cli/src/app/manifest/README.md+++ b/packages/twenty-cli/src/app/manifest/README.md@@ -57,18 +57,16 @@ From `packages/twenty-cli`, after building the repository SDK, shared and UIpackages:```bash-node ../../node_modules/vitest/vitest.mjs run --config vitest.config.ts --maxWorkers=1 src/app/manifest/__tests__/manifest-parity.spec.ts+node ../../node_modules/vitest/vitest.mjs run --config vitest.config.ts --maxWorkers=1 src/app/manifest/__tests__/manifest-fixtures.spec.ts```-The suite bundles the SDK implementation as a test-only reference. It-compares manifests, entity file paths, errors and warnings for every repository-fixture and a freshly initialized app. It also exercises the production CLI-worker using a copy of the real SDK's authoring entry points without `./build`,-`./cli` or their implementation files.+The suite compares manifests, entity file paths, errors and warnings against+checked-in expectations for every repository fixture and a freshly initialized+app. It exercises the production CLI worker using a copy of the real SDK's+authoring entry points without `./build`, `./cli` or their implementation files.-The SDK reference's discovery is sorted to match the CLI's deterministic input-order. Comparisons remove only JSON-omitted `undefined` properties, matching the-worker IPC boundary; arrays and diagnostics are not reordered. The invalid-app-fixture throws `Invalid UUID` in both implementations. Additional cases cover-duplicate identifiers, empty lockfiles, translations, source output and credential filtering.-Unit tests cover individual validation and translation rules.+Comparisons remove only JSON-omitted `undefined` properties, matching the worker+IPC boundary; arrays and diagnostics are not reordered. Additional cases cover+invalid and duplicate identifiers, empty lockfiles, translations, source output+and credential filtering. Unit tests cover individual validation and translation+rules.diff --git a/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap b/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snapnew file mode 100644index 00000000000..4fe009b9dee--- /dev/null+++ b/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap@@ -0,0 +1,1518 @@+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html++exports[`CLI manifest fixtures and worker transport > matches the manifest, file paths, errors and warnings for function-execute-app 1`] = `+{+ "filePaths": {+ "agents": [],+ "application": [+ "application.config.ts",+ ],+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [],+ "frontComponents": [],+ "indexes": [],+ "logicFunctions": [+ "src/logic-functions/add-numbers.function.ts",+ ],+ "navigationMenuItems": [],+ "objects": [],+ "pageLayoutTabs": [],+ "pageLayoutWidgets": [],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [],+ "roles": [+ "my.role.ts",+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [],+ "viewFields": [],+ "views": [],+ "workflows": [],+ },+ "manifest": {+ "agents": [],+ "application": {+ "aboutDescription": "# Function Execute Test App++Fixture app used to exercise logic-function execution in CLI tests.++Build the standalone CLI from the repository root before using this fixture's \`dev\`, \`exec\`, or \`uninstall\` scripts:++\`\`\`bash+npx nx build twenty-cli+\`\`\`++The scripts invoke that local build directly, so the SDK binary cannot shadow it.+",+ "defaultRoleUniversalIdentifier": "9f992b6c-17e9-4381-bab5-b6150b574304",+ "description": "A minimal app for testing function:execute",+ "displayName": "Function Execute Test App",+ "galleryImages": [],+ "packageJsonChecksum": null,+ "requiredServerVersionRange": null,+ "universalIdentifier": "01e065d6-1b48-4107-86d8-b06f87420a4f",+ "yarnLockChecksum": null,+ },+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [],+ "frontComponents": [],+ "indexes": [],+ "logicFunctions": [+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/add-numbers.function.mjs",+ "handlerName": "default.config.handler",+ "httpRouteTriggerSettings": {+ "httpMethod": "GET",+ "isAuthRequired": false,+ "path": "/add-numbers",+ },+ "name": "add-numbers",+ "sourceHandlerPath": "src/logic-functions/add-numbers.function.ts",+ "timeoutSeconds": 5,+ "universalIdentifier": "f9e5589c-e951-4d99-85db-0a305ab53502",+ },+ ],+ "navigationMenuItems": [],+ "objects": [],+ "pageLayoutTabs": [],+ "pageLayoutWidgets": [],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [],+ "roles": [+ {+ "canBeAssignedToAgents": false,+ "canBeAssignedToApiKeys": false,+ "canBeAssignedToUsers": true,+ "canDestroyAllObjectRecords": false,+ "canReadAllObjectRecords": true,+ "canSoftDeleteAllObjectRecords": false,+ "canUpdateAllObjectRecords": false,+ "canUpdateAllSettings": false,+ "description": "Default role for function execute test app",+ "fieldPermissions": [],+ "label": "Default role",+ "objectPermissions": [],+ "permissionFlagUniversalIdentifiers": [],+ "rowLevelPermissionPredicateGroups": [],+ "rowLevelPermissionPredicates": [],+ "universalIdentifier": "9f992b6c-17e9-4381-bab5-b6150b574304",+ },+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [],+ "viewFields": [],+ "views": [],+ "workflows": [],+ },+ "success": true,+ "warnings": [+ "\`defaultRoleUniversalIdentifier\` on defineApplication() is deprecated. Use defineApplicationRole() in your role file instead.",+ ""twenty-sdk" is listed under "dependencies" in package.json. It is a build-time only tool and should be moved to "devDependencies".",+ ""twenty-client-sdk" is listed under "dependencies" in package.json. It is provided at runtime by Twenty's injected SDK and should be moved to "devDependencies".",+ ],+}+`;++exports[`CLI manifest fixtures and worker transport > matches the manifest, file paths, errors and warnings for invalid-app 1`] = `+{+ "errors": [+ "Invalid UUID",+ ],+ "success": false,+}+`;++exports[`CLI manifest fixtures and worker transport > matches the manifest, file paths, errors and warnings for minimal-app 1`] = `+{+ "filePaths": {+ "agents": [],+ "application": [+ "application.config.ts",+ ],+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [],+ "frontComponents": [+ "my.front-component.tsx",+ ],+ "indexes": [],+ "logicFunctions": [+ "my.function.ts",+ ],+ "navigationMenuItems": [],+ "objects": [+ "my.object.ts",+ ],+ "pageLayoutTabs": [],+ "pageLayoutWidgets": [],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [],+ "roles": [+ "my.role.ts",+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [],+ "viewFields": [],+ "views": [],+ "workflows": [],+ },+ "manifest": {+ "agents": [],+ "application": {+ "defaultRoleUniversalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000040",+ "description": "An app with all entities at root level",+ "displayName": "Root App",+ "galleryImages": [],+ "packageJsonChecksum": null,+ "requiredServerVersionRange": null,+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000001",+ "yarnLockChecksum": null,+ },+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [],+ "frontComponents": [+ {+ "builtComponentChecksum": "",+ "builtComponentPath": "my.front-component.mjs",+ "componentName": "MyComponent",+ "description": "A root-level front component",+ "isHeadless": false,+ "name": "my-component",+ "sourceComponentPath": "my.front-component.tsx",+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000020",+ },+ ],+ "indexes": [],+ "logicFunctions": [+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "my.function.mjs",+ "handlerName": "default.config.handler",+ "httpRouteTriggerSettings": {+ "httpMethod": "GET",+ "isAuthRequired": false,+ "path": "/my-function",+ },+ "name": "my-function",+ "sourceHandlerPath": "my.function.ts",+ "timeoutSeconds": 5,+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000010",+ },+ ],+ "navigationMenuItems": [],+ "objects": [+ {+ "description": "A simple root-level object",+ "fields": [+ {+ "label": "Title",+ "name": "title",+ "type": "TEXT",+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000031",+ },+ {+ "defaultValue": null,+ "description": "Name",+ "icon": "IconAbc",+ "isNullable": true,+ "label": "Name",+ "name": "name",+ "type": "TEXT",+ "universalIdentifier": "9a7f457a-6c15-581e-8f28-e2c680f75f97",+ },+ ],+ "icon": "IconNote",+ "labelIdentifierFieldMetadataUniversalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000031",+ "labelPlural": "My notes",+ "labelSingular": "My note",+ "namePlural": "myNotes",+ "nameSingular": "myNote",+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000030",+ },+ ],+ "pageLayoutTabs": [],+ "pageLayoutWidgets": [],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [],+ "roles": [+ {+ "canBeAssignedToAgents": false,+ "canBeAssignedToApiKeys": false,+ "canBeAssignedToUsers": true,+ "canDestroyAllObjectRecords": false,+ "canReadAllObjectRecords": true,+ "canSoftDeleteAllObjectRecords": false,+ "canUpdateAllObjectRecords": false,+ "canUpdateAllSettings": false,+ "description": "A simple root-level role",+ "fieldPermissions": [],+ "label": "My role",+ "objectPermissions": [],+ "permissionFlagUniversalIdentifiers": [],+ "rowLevelPermissionPredicateGroups": [],+ "rowLevelPermissionPredicates": [],+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000040",+ },+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [],+ "viewFields": [],+ "views": [],+ "workflows": [],+ },+ "success": true,+ "warnings": [+ "\`defaultRoleUniversalIdentifier\` on defineApplication() is deprecated. Use defineApplicationRole() in your role file instead.",+ "Front component "my-component" declares no widgetAvailability, so it is not offered in any widget picker. Set widgetAvailability to let users add it to record pages or dashboards.",+ ""twenty-sdk" is listed under "dependencies" in package.json. It is a build-time only tool and should be moved to "devDependencies".",+ ""twenty-client-sdk" is listed under "dependencies" in package.json. It is provided at runtime by Twenty's injected SDK and should be moved to "devDependencies".",+ ],+}+`;++exports[`CLI manifest fixtures and worker transport > matches the manifest, file paths, errors and warnings for rich-app 1`] = `+{+ "filePaths": {+ "agents": [],+ "application": [+ "application.config.ts",+ ],+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [+ "src/fields/company-can-receive-postcards.field.ts",+ "src/fields/post-card-category.field.ts",+ "src/fields/post-card-number.field.ts",+ "src/fields/post-card-on-post-card-recipient.field.ts",+ "src/fields/post-card-recipients-on-post-card.field.ts",+ "src/fields/post-card-recipients-on-recipient.field.ts",+ "src/fields/recipient-on-post-card-recipient.field.ts",+ ],+ "frontComponents": [+ "src/components/card.front-component.tsx",+ "src/components/greeting.front-component.tsx",+ "src/components/test.front-component.tsx",+ "src/root.front-component.tsx",+ ],+ "indexes": [+ "src/indexes/post-card-status.index.ts",+ ],+ "logicFunctions": [+ "src/logic-functions/enrich-post-cards.function.ts",+ "src/logic-functions/greeting.function.ts",+ "src/logic-functions/lookup-recipient.function.ts",+ "src/logic-functions/on-post-card-created.function.ts",+ "src/logic-functions/test-function-2.function.ts",+ "src/logic-functions/test-function.function.ts",+ "src/root.function.ts",+ ],+ "navigationMenuItems": [+ "src/navigation-menu-items/post-card-recipients.navigation-menu-item.ts",+ "src/navigation-menu-items/post-cards.navigation-menu-item.ts",+ "src/navigation-menu-items/recipients.navigation-menu-item.ts",+ ],+ "objects": [+ "src/objects/post-card-recipient.object.ts",+ "src/objects/post-card.object.ts",+ "src/objects/recipient.object.ts",+ "src/root.object.ts",+ ],+ "pageLayoutTabs": [+ "src/page-layout-tabs/extra-tab.page-layout-tab.ts",+ ],+ "pageLayoutWidgets": [+ "src/page-layout-widgets/extra-widget.page-layout-widget.ts",+ ],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [+ "public/favicon.png",+ ],+ "roles": [+ "src/roles/default-function.role.ts",+ "src/root.role.ts",+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [+ "src/timeline-activity-types/post-card-created.timeline-activity-type.ts",+ "src/timeline-activity-types/post-card-linked.timeline-activity-type.ts",+ ],+ "viewFields": [+ "src/viewFields/post-card-number-view-field.ts",+ ],+ "views": [+ "src/views/all-post-card-recipients.view.ts",+ "src/views/all-post-cards.view.ts",+ "src/views/all-recipients.view.ts",+ "src/views/post-cards-by-delivery-date.view.ts",+ "src/views/post-cards-by-status.view.ts",+ ],+ "workflows": [],+ },+ "manifest": {+ "agents": [],+ "application": {+ "applicationVariables": {+ "ALLOWED_TAGS": {+ "description": "Free-form tags applied to recipients",+ "type": "ARRAY",+ "universalIdentifier": "c1c8a4c9-9130-4ab8-8dce-18d2b50879ed",+ "value": [+ "vip",+ "returning",+ ],+ },+ "CAMPAIGN_START_AT": {+ "description": "Exact moment the campaign starts",+ "type": "DATE_TIME",+ "universalIdentifier": "273d0cfd-d6ab-4148-8816-c4a5d4b1d600",+ "value": "2026-01-01T09:00:00.000Z",+ },+ "CAMPAIGN_START_DATE": {+ "description": "Date the campaign starts",+ "type": "DATE",+ "universalIdentifier": "5aa4fcec-e8a3-4bc1-9c7f-762e1f9dfb40",+ "value": "2026-01-01",+ },+ "DEFAULT_RECIPIENT_NAME": {+ "description": "Default recipient name for postcards",+ "isSecret": false,+ "universalIdentifier": "19e94e59-d4fe-4251-8981-b96d0a9f74de",+ "value": "Alex Karp",+ },+ "DEFAULT_REGION": {+ "description": "Default shipping region",+ "options": [+ {+ "label": "Europe",+ "value": "eu",+ },+ {+ "label": "United States",+ "value": "us",+ },+ {+ "label": "Asia-Pacific",+ "value": "apac",+ },+ ],+ "type": "SELECT",+ "universalIdentifier": "76c5c321-b6b6-46eb-b4fc-f9f04bb04227",+ "value": "eu",+ },+ "DISCOUNT_RATE": {+ "description": "Bulk discount rate applied at checkout",+ "type": "NUMERIC",+ "universalIdentifier": "d32f810f-06bb-4d29-b0ee-1dc4228f7cb8",+ "value": 2.5,+ },+ "ENABLED_CHANNELS": {+ "description": "Channels the app is allowed to use",+ "options": [+ {+ "label": "Email",+ "value": "email",+ },+ {+ "label": "SMS",+ "value": "sms",+ },+ {+ "label": "Postcard",+ "value": "postcard",+ },+ ],+ "type": "MULTI_SELECT",+ "universalIdentifier": "706a2b08-8284-4715-8bc0-922a99cb26af",+ "value": [+ "email",+ "postcard",+ ],+ },+ "ENABLE_TRACKING": {+ "description": "Toggle delivery tracking",+ "type": "BOOLEAN",+ "universalIdentifier": "b9c58bb2-58c3-4c6c-9877-498ea6c03fde",+ "value": true,+ },+ "GREETING_TEXT": {+ "description": "Free text shown on the postcard",+ "type": "TEXT",+ "universalIdentifier": "ad19edc5-4cc5-4003-a996-aef53a5c8de0",+ "value": "Hello from Rich App",+ },+ "MAX_POSTCARDS": {+ "description": "Maximum postcards per batch",+ "type": "NUMBER",+ "universalIdentifier": "5f4497e4-9030-4085-85eb-2c48b8d53713",+ "value": 10,+ },+ "PROVIDER_CONFIG": {+ "description": "Raw JSON configuration for the printing provider",+ "type": "RAW_JSON",+ "universalIdentifier": "183d5285-c70c-4f29-96e0-c68659fbe5ae",+ "value": {+ "retries": 3,+ "timeoutMs": 5000,+ },+ },+ "WELCOME_MESSAGE": {+ "description": "Rich text welcome message",+ "type": "RICH_TEXT",+ "universalIdentifier": "25a66ff5-8458-498e-9e7e-33ea458a6f3c",+ "value": {+ "blocknote": null,+ "markdown": "Welcome to **Rich App**!",+ },+ },+ },+ "defaultRoleUniversalIdentifier": "b648f87b-1d26-4961-b974-0908fd991061",+ "description": "A simple rich app",+ "displayName": "Rich App",+ "galleryImages": [],+ "packageJsonChecksum": null,+ "requiredServerVersionRange": null,+ "serverVariables": {+ "POSTCARD_API_KEY": {+ "description": "API key for the postcard printing service",+ "isRequired": true,+ "isSecret": true,+ },+ "POSTCARD_CONTRACT_RENEWAL_AT": {+ "description": "Exact moment the provider contract renews",+ "isRequired": false,+ "isSecret": false,+ "type": "DATE_TIME",+ },+ "POSTCARD_CONTRACT_START_DATE": {+ "description": "Date the provider contract starts",+ "isRequired": false,+ "isSecret": false,+ "type": "DATE",+ },+ "POSTCARD_DAILY_LIMIT": {+ "description": "Maximum postcards the provider will accept per day",+ "isRequired": false,+ "isSecret": false,+ "type": "NUMBER",+ },+ "POSTCARD_DELIVERY_SPEED": {+ "description": "Delivery speed requested from the provider",+ "isRequired": true,+ "isSecret": false,+ "options": [+ {+ "label": "Standard",+ "value": "standard",+ },+ {+ "label": "Express",+ "value": "express",+ },+ ],+ "type": "SELECT",+ },+ "POSTCARD_ENABLED_REGIONS": {+ "description": "Regions the provider is allowed to ship to",+ "isRequired": false,+ "isSecret": false,+ "options": [+ {+ "label": "Europe",+ "value": "eu",+ },+ {+ "label": "United States",+ "value": "us",+ },+ {+ "label": "Asia-Pacific",+ "value": "apac",+ },+ ],+ "type": "MULTI_SELECT",+ },+ "POSTCARD_INVOICE_NOTE": {+ "description": "Rich text note appended to provider invoices",+ "isRequired": false,+ "isSecret": false,+ "type": "RICH_TEXT",+ },+ "POSTCARD_PROVIDER_CONFIG": {+ "description": "Raw JSON configuration for the printing provider",+ "isRequired": false,+ "isSecret": false,+ "type": "RAW_JSON",+ },+ "POSTCARD_SANDBOX_MODE": {+ "description": "Send postcards through the provider sandbox instead of production",+ "isRequired": false,+ "isSecret": false,+ "type": "BOOLEAN",+ },+ "POSTCARD_SENDER_NAME": {+ "description": "Default sender name on postcards",+ "isRequired": false,+ "isSecret": false,+ },+ "POSTCARD_UNIT_PRICE": {+ "description": "Price charged by the provider per postcard",+ "isRequired": false,+ "isSecret": false,+ "type": "NUMERIC",+ },+ "POSTCARD_WEBHOOK_EVENTS": {+ "description": "Provider webhook events the app subscribes to",+ "isRequired": false,+ "isSecret": false,+ "type": "ARRAY",+ },+ },+ "universalIdentifier": "4ec0391d-18d5-411c-b2f3-266ddc1c3ef7",+ "yarnLockChecksum": null,+ },+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [+ {+ "description": "Priority level for the post card (1-10)",+ "label": "Priority",+ "name": "priority",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "type": "NUMBER",+ "universalIdentifier": "7b57bd63-5a4c-46ca-9d52-42c8f02d1df6",+ },+ {+ "label": "Post Card Recipients",+ "name": "postCardRecipients",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "relationTargetFieldMetadataUniversalIdentifier": "a1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d",+ "relationTargetObjectMetadataUniversalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "type": "RELATION",+ "universalIdentifier": "a1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d",+ "universalSettings": {+ "junctionTargetFieldUniversalIdentifier": "a1a2b3c4-0004-4a7b-8c9d-0e1f2a3b4c5d",+ "relationType": "ONE_TO_MANY",+ },+ },+ {+ "label": "Post Card",+ "name": "postCard",+ "objectUniversalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "relationTargetFieldMetadataUniversalIdentifier": "a1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d",+ "relationTargetObjectMetadataUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "type": "RELATION",+ "universalIdentifier": "a1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d",+ "universalSettings": {+ "joinColumnName": "postCardId",+ "onDelete": "CASCADE",+ "relationType": "MANY_TO_ONE",+ },+ },+ {+ "label": "Post Card Recipients",+ "name": "postCardRecipients",+ "objectUniversalIdentifier": "d1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ "relationTargetFieldMetadataUniversalIdentifier": "a1a2b3c4-0004-4a7b-8c9d-0e1f2a3b4c5d",+ "relationTargetObjectMetadataUniversalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "type": "RELATION",+ "universalIdentifier": "a1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d",+ "universalSettings": {+ "relationType": "ONE_TO_MANY",+ },+ },+ {+ "label": "Recipient",+ "name": "recipient",+ "objectUniversalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "relationTargetFieldMetadataUniversalIdentifier": "a1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d",+ "relationTargetObjectMetadataUniversalIdentifier": "d1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ "type": "RELATION",+ "universalIdentifier": "a1a2b3c4-0004-4a7b-8c9d-0e1f2a3b4c5d",+ "universalSettings": {+ "joinColumnName": "recipientId",+ "onDelete": "CASCADE",+ "relationType": "MANY_TO_ONE",+ },+ },+ {+ "description": "Post card category",+ "label": "Category",+ "name": "category",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "options": [+ {+ "color": "blue",+ "id": "cd751c81-787d-4581-bc51-efe43f0050a7",+ "label": "Personal",+ "position": 0,+ "value": "PERSONAL",+ },+ {+ "color": "green",+ "id": "eec437ca-5beb-41a9-a826-c9a5eca2eef4",+ "label": "Business",+ "position": 1,+ "value": "BUSINESS",+ },+ {+ "color": "orange",+ "id": "a5baa37d-1047-4972-b6b8-7faae0e3eac1",+ "label": "Promotional",+ "position": 2,+ "value": "PROMOTIONAL",+ },+ {+ "color": "gray",+ "id": "877336e4-6591-599f-8cd1-4c7dfae623d7",+ "label": "Other",+ "position": 3,+ "value": "OTHER",+ },+ ],+ "type": "SELECT",+ "universalIdentifier": "b602dbd9-e511-49ce-b6d3-b697218dc69c",+ },+ {+ "defaultValue": false,+ "description": "Whether the company can receive postcards",+ "icon": "IconMailbox",+ "label": "Can Receive Postcards",+ "name": "canReceivePostcards",+ "objectUniversalIdentifier": "20202020-b374-4779-a561-80086cb2e17f",+ "type": "BOOLEAN",+ "universalIdentifier": "f922fdb8-10a9-4f11-a1d0-992a779f6dff",+ },+ ],+ "frontComponents": [+ {+ "builtComponentChecksum": "",+ "builtComponentPath": "src/components/greeting.front-component.mjs",+ "componentName": "GreetingComponent",+ "description": "A component that uses greeting utility",+ "isHeadless": false,+ "name": "greeting-component",+ "sourceComponentPath": "src/components/greeting.front-component.tsx",+ "universalIdentifier": "370ae182-743f-4ecb-b625-7ac48e21f0e5",+ },+ {+ "builtComponentChecksum": "",+ "builtComponentPath": "src/components/card.front-component.mjs",+ "componentName": "CardDisplay",+ "description": "A component using an external component file",+ "isHeadless": false,+ "name": "card-component",+ "sourceComponentPath": "src/components/card.front-component.tsx",+ "universalIdentifier": "88c15ae2-5f87-4a6b-b48f-1974bbe62eb7",+ },+ {+ "builtComponentChecksum": "",+ "builtComponentPath": "src/root.front-component.mjs",+ "componentName": "RootComponent",+ "description": "A root-level front component",+ "isHeadless": false,+ "name": "root-component",+ "sourceComponentPath": "src/root.front-component.tsx",+ "universalIdentifier": "a0a1a2a3-a4a5-4000-8000-000000000001",+ },+ {+ "builtComponentChecksum": "",+ "builtComponentPath": "src/components/test.front-component.mjs",+ "componentName": "TestComponent",+ "description": "A test front component",+ "isHeadless": false,+ "name": "test-component",+ "sourceComponentPath": "src/components/test.front-component.tsx",+ "universalIdentifier": "f1234567-abcd-4000-8000-000000000001",+ },+ ],+ "indexes": [+ {+ "fields": [+ {+ "fieldUniversalIdentifier": "87b675b8-dd8c-4448-b4ca-20e5a2234a1e",+ "universalIdentifier": "b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff1",+ },+ ],+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "universalIdentifier": "b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff0",+ },+ ],+ "logicFunctions": [+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/greeting.function.mjs",+ "handlerName": "default.config.handler",+ "httpRouteTriggerSettings": {+ "httpMethod": "GET",+ "isAuthRequired": false,+ "path": "/greet",+ },+ "name": "greeting-function",+ "sourceHandlerPath": "src/logic-functions/greeting.function.ts",+ "timeoutSeconds": 5,+ "universalIdentifier": "9d412d9e-2caf-487c-8b66-d1585883dd4e",+ },+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/lookup-recipient.function.mjs",+ "description": "Look up a recipient by name to find their details",+ "handlerName": "default.config.handler",+ "name": "lookup-recipient",+ "sourceHandlerPath": "src/logic-functions/lookup-recipient.function.ts",+ "timeoutSeconds": 5,+ "toolTriggerSettings": {+ "inputSchema": {+ "properties": {+ "recipientName": {+ "type": "string",+ },+ },+ "required": [+ "recipientName",+ ],+ "type": "object",+ },+ },+ "universalIdentifier": "a1b2c3d4-1001-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/enrich-post-cards.function.mjs",+ "description": "Enrich post cards of a company",+ "handlerName": "default.config.handler",+ "name": "enrich-post-cards",+ "sourceHandlerPath": "src/logic-functions/enrich-post-cards.function.ts",+ "timeoutSeconds": 5,+ "universalIdentifier": "a1b2c3d4-ac10-4a7b-8c9d-0e1f2a3b4c5d",+ "workflowActionTriggerSettings": {+ "icon": "IconMail",+ "inputSchema": [+ {+ "properties": {+ "companyId": {+ "objectUniversalIdentifier": "20202020-b374-4779-a561-80086cb2e17f",+ "type": "record",+ },+ "postCardIds": {+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "type": "records",+ },+ },+ "type": "object",+ },+ ],+ "label": "Enrich Post Cards",+ },+ },+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/on-post-card-created.function.mjs",+ "databaseEventTriggerSettings": {+ "eventName": "postCard.created",+ },+ "description": "Triggered when a new post card is created",+ "handlerName": "default.config.handler",+ "name": "on-post-card-created",+ "sourceHandlerPath": "src/logic-functions/on-post-card-created.function.ts",+ "timeoutSeconds": 5,+ "universalIdentifier": "a1b2c3d4-db01-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/test-function.function.mjs",+ "handlerName": "default.config.handler",+ "httpRouteTriggerSettings": {+ "forwardedRequestHeaders": [+ "signature",+ ],+ "httpMethod": "GET",+ "isAuthRequired": false,+ "path": "/post-card/create",+ },+ "name": "test-function",+ "sourceHandlerPath": "src/logic-functions/test-function.function.ts",+ "timeoutSeconds": 2,+ "universalIdentifier": "e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf",+ },+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/logic-functions/test-function-2.function.mjs",+ "cronTriggerSettings": {+ "pattern": "0 0 1 1 *",+ },+ "handlerName": "default.config.handler",+ "name": "test-function-2",+ "sourceHandlerPath": "src/logic-functions/test-function-2.function.ts",+ "timeoutSeconds": 2,+ "universalIdentifier": "eb3ffc98-88ec-45d4-9b4a-56833b219ccb",+ },+ {+ "builtHandlerChecksum": "[default-checksum]",+ "builtHandlerPath": "src/root.function.mjs",+ "handlerName": "default.config.handler",+ "httpRouteTriggerSettings": {+ "httpMethod": "GET",+ "isAuthRequired": false,+ "path": "/root",+ },+ "name": "root-function",+ "sourceHandlerPath": "src/root.function.ts",+ "timeoutSeconds": 5,+ "universalIdentifier": "f0f1f2f3-f4f5-4000-8000-000000000001",+ },+ ],+ "navigationMenuItems": [+ {+ "position": 1,+ "targetObjectUniversalIdentifier": "d1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ "type": "OBJECT",+ "universalIdentifier": "c1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "position": 2,+ "targetObjectUniversalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "type": "OBJECT",+ "universalIdentifier": "c1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "position": 0,+ "targetObjectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "type": "OBJECT",+ "universalIdentifier": "e8031eca-d6ea-4a4b-b828-38227dba896a",+ },+ ],+ "objects": [+ {+ "description": "A post card object",+ "fields": [+ {+ "description": "Postcard's content",+ "icon": "IconAbc",+ "label": "Content",+ "name": "content",+ "type": "TEXT",+ "universalIdentifier": "58a0a314-d7ea-4865-9850-7fb84e72f30b",+ },+ {+ "icon": "IconUser",+ "label": "Recipient name",+ "name": "recipientName",+ "type": "FULL_NAME",+ "universalIdentifier": "c6aa31f3-da76-4ac6-889f-475e226009ac",+ },+ {+ "icon": "IconHome",+ "label": "Recipient address",+ "name": "recipientAddress",+ "type": "ADDRESS",+ "universalIdentifier": "95045777-a0ad-49ec-98f9-22f9fc0c8266",+ },+ {+ "defaultValue": "'DRAFT'",+ "icon": "IconSend",+ "label": "Status",+ "name": "status",+ "options": [+ {+ "color": "gray",+ "id": "1b008e19-1e59-4a07-b187-65a20e547c4e",+ "label": "Draft",+ "position": 0,+ "value": "DRAFT",+ },+ {+ "color": "orange",+ "id": "452b9d40-889c-4342-9697-98319394db04",+ "label": "Sent",+ "position": 1,+ "value": "SENT",+ },+ {+ "color": "green",+ "id": "c2ed0b8c-a3ed-4383-aef9-e0441267bcfe",+ "label": "Delivered",+ "position": 2,+ "value": "DELIVERED",+ },+ {+ "color": "orange",+ "id": "c57a5e08-7ef7-49b8-87e6-32d720d22802",+ "label": "Returned",+ "position": 3,+ "value": "RETURNED",+ },+ {+ "color": "red",+ "id": "5248e3c4-23f8-512d-9bea-5c2df85bf83c",+ "label": "Lost",+ "position": 4,+ "value": "LOST",+ },+ ],+ "type": "SELECT",+ "universalIdentifier": "87b675b8-dd8c-4448-b4ca-20e5a2234a1e",+ },+ {+ "defaultValue": null,+ "icon": "IconCheck",+ "isNullable": true,+ "label": "Delivered at",+ "name": "deliveredAt",+ "type": "DATE_TIME",+ "universalIdentifier": "e06abe72-5b44-4e7f-93be-afc185a3c433",+ },+ {+ "defaultValue": null,+ "description": "Name",+ "icon": "IconAbc",+ "isNullable": true,+ "label": "Name",+ "name": "name",+ "type": "TEXT",+ "universalIdentifier": "3e14e30f-8271-5a13-9c1f-ce5edb932325",+ },+ ],+ "icon": "IconMail",+ "labelIdentifierFieldMetadataUniversalIdentifier": "58a0a314-d7ea-4865-9850-7fb84e72f30b",+ "labelPlural": "Post cards",+ "labelSingular": "Post card",+ "namePlural": "postCards",+ "nameSingular": "postCard",+ "universalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ },+ {+ "description": "A simple root-level object",+ "fields": [+ {+ "label": "Title",+ "name": "title",+ "type": "TEXT",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000002",+ },+ {+ "label": "Body",+ "name": "body",+ "type": "TEXT",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000003",+ },+ {+ "defaultValue": null,+ "description": "Name",+ "icon": "IconAbc",+ "isNullable": true,+ "label": "Name",+ "name": "name",+ "type": "TEXT",+ "universalIdentifier": "10452ca3-30cb-56fa-9e58-73f7b1c9fd65",+ },+ ],+ "icon": "IconNote",+ "labelIdentifierFieldMetadataUniversalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000002",+ "labelPlural": "Root notes",+ "labelSingular": "Root note",+ "namePlural": "rootNotes",+ "nameSingular": "rootNote",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000001",+ },+ {+ "description": "A person or organization that receives post cards",+ "fields": [+ {+ "icon": "IconMail",+ "label": "Email",+ "name": "email",+ "type": "EMAILS",+ "universalIdentifier": "d2a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "icon": "IconHome",+ "label": "Mailing Address",+ "name": "mailingAddress",+ "type": "ADDRESS",+ "universalIdentifier": "d3a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "defaultValue": null,+ "description": "Name",+ "icon": "IconAbc",+ "isNullable": true,+ "label": "Name",+ "name": "name",+ "type": "TEXT",+ "universalIdentifier": "c400ccb8-cd91-5ae1-81e3-2df8b6f2cf53",+ },+ ],+ "icon": "IconUser",+ "labelIdentifierFieldMetadataUniversalIdentifier": "c400ccb8-cd91-5ae1-81e3-2df8b6f2cf53",+ "labelPlural": "Recipients",+ "labelSingular": "Recipient",+ "namePlural": "recipients",+ "nameSingular": "recipient",+ "universalIdentifier": "d1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "description": "Junction object linking post cards to their recipients",+ "fields": [+ {+ "defaultValue": null,+ "icon": "IconClock",+ "isNullable": true,+ "label": "Sent at",+ "name": "sentAt",+ "type": "DATE_TIME",+ "universalIdentifier": "e2a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ },+ {+ "defaultValue": null,+ "description": "Name",+ "icon": "IconAbc",+ "isNullable": true,+ "label": "Name",+ "name": "name",+ "type": "TEXT",+ "universalIdentifier": "f485cd3a-4c55-5b8f-b926-a83e5e6ba651",+ },+ ],+ "icon": "IconLink",+ "labelIdentifierFieldMetadataUniversalIdentifier": "f485cd3a-4c55-5b8f-b926-a83e5e6ba651",+ "labelPlural": "Post Card Recipients",+ "labelSingular": "Post Card Recipient",+ "namePlural": "postCardRecipients",+ "nameSingular": "postCardRecipient",+ "universalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ },+ ],+ "pageLayoutTabs": [+ {+ "icon": "IconLayout",+ "layoutMode": "VERTICAL_LIST",+ "pageLayoutUniversalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000020",+ "position": 1000,+ "title": "Extra Tab",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000010",+ "widgets": [+ {+ "configuration": {+ "aggregateFieldMetadataUniversalIdentifier": "7b57bd63-5a4c-46ca-9d52-42c8f02d1df6",+ "aggregateOperation": "SUM",+ "configurationType": "AGGREGATE_CHART",+ },+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "title": "Total Priority",+ "type": "GRAPH",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000012",+ },+ {+ "configuration": {+ "configurationType": "FRONT_COMPONENT",+ "frontComponentUniversalIdentifier": "370ae182-743f-4ecb-b625-7ac48e21f0e5",+ },+ "heightBehavior": "TAB_VIEWPORT",+ "title": "Extra Widget",+ "type": "FRONT_COMPONENT",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000011",+ },+ ],+ },+ ],+ "pageLayoutWidgets": [+ {+ "configuration": {+ "configurationType": "FRONT_COMPONENT",+ "frontComponentUniversalIdentifier": "370ae182-743f-4ecb-b625-7ac48e21f0e5",+ },+ "pageLayoutTabUniversalIdentifier": "553effdf-552a-5c59-a2e7-a72d019b9927",+ "position": {+ "index": 1000,+ "layoutMode": "VERTICAL_LIST",+ },+ "title": "Extra Home Widget",+ "type": "FRONT_COMPONENT",+ "universalIdentifier": "b0b1b2b3-b4b5-4000-8000-000000000013",+ },+ ],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [+ {+ "checksum": null,+ "fileName": "favicon.png",+ "filePath": "public/favicon.png",+ "fileType": "png",+ },+ ],+ "roles": [+ {+ "canBeAssignedToAgents": false,+ "canBeAssignedToApiKeys": false,+ "canBeAssignedToUsers": false,+ "canDestroyAllObjectRecords": false,+ "canReadAllObjectRecords": false,+ "canSoftDeleteAllObjectRecords": false,+ "canUpdateAllObjectRecords": false,+ "canUpdateAllSettings": false,+ "description": "Default role for function Twenty client",+ "fieldPermissions": [+ {+ "canReadFieldValue": false,+ "canUpdateFieldValue": false,+ "fieldUniversalIdentifier": "58a0a314-d7ea-4865-9850-7fb84e72f30b",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "universalIdentifier": "d0b74fcb-3993-5ff9-bbd6-d76ea9b6493f",+ },+ ],+ "label": "Default function role",+ "objectPermissions": [+ {+ "canDestroyObjectRecords": false,+ "canReadObjectRecords": true,+ "canSoftDeleteObjectRecords": false,+ "canUpdateObjectRecords": true,+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "universalIdentifier": "fab82874-880a-556f-93d9-626610bb0770",+ },+ {+ "canDestroyObjectRecords": false,+ "canReadObjectRecords": true,+ "canSoftDeleteObjectRecords": false,+ "canUpdateObjectRecords": true,+ "objectUniversalIdentifier": "20202020-6736-4337-b5c4-8b39fae325a5",+ "universalIdentifier": "518fbc62-c198-5e31-8df8-c79402aa84b4",+ },+ ],+ "permissionFlagUniversalIdentifiers": [+ "9faa55f7-2606-566b-9e1d-aefbedbd0136",+ ],+ "rowLevelPermissionPredicateGroups": [],+ "rowLevelPermissionPredicates": [],+ "universalIdentifier": "b648f87b-1d26-4961-b974-0908fd991061",+ },+ {+ "canBeAssignedToAgents": false,+ "canBeAssignedToApiKeys": false,+ "canBeAssignedToUsers": true,+ "canDestroyAllObjectRecords": false,+ "canReadAllObjectRecords": true,+ "canSoftDeleteAllObjectRecords": false,+ "canUpdateAllObjectRecords": false,+ "canUpdateAllSettings": false,+ "description": "A simple root-level role",+ "fieldPermissions": [],+ "label": "Root role",+ "objectPermissions": [],+ "permissionFlagUniversalIdentifiers": [],+ "rowLevelPermissionPredicateGroups": [],+ "rowLevelPermissionPredicates": [],+ "universalIdentifier": "c0c1c2c3-c4c5-4000-8000-000000000001",+ },+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [+ {+ "frontComponentUniversalIdentifier": "88c15ae2-5f87-4a6b-b48f-1974bbe62eb7",+ "icon": "IconMail",+ "label": "created a post card",+ "name": "postCardCreated",+ "universalIdentifier": "f4fa646c-6e11-4d8f-a6be-c3b7a2fc7500",+ },+ {+ "emit": {+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "on": "linked",+ "through": {+ "relationFieldUniversalIdentifier": "a1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d",+ },+ },+ "frontComponentUniversalIdentifier": "88c15ae2-5f87-4a6b-b48f-1974bbe62eb7",+ "icon": "IconMail",+ "label": "received a post card",+ "name": "postCardLinked",+ "universalIdentifier": "f4fa646c-6e11-4d8f-a6be-c3b7a2fc7501",+ },+ ],+ "viewFields": [+ {+ "fieldMetadataUniversalIdentifier": "7b57bd63-5a4c-46ca-9d52-42c8f02d1df6",+ "isVisible": true,+ "position": 5,+ "universalIdentifier": "cd582d11-ea21-4dc3-b9c1-0298ce3b6b54",+ "viewUniversalIdentifier": "b1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d",+ },+ ],+ "views": [+ {+ "fields": [+ {+ "fieldMetadataUniversalIdentifier": "58a0a314-d7ea-4865-9850-7fb84e72f30b",+ "isVisible": true,+ "position": 0,+ "size": 200,+ "universalIdentifier": "bf1a2b3c-0001-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "fieldMetadataUniversalIdentifier": "87b675b8-dd8c-4448-b4ca-20e5a2234a1e",+ "isVisible": true,+ "position": 1,+ "size": 150,+ "universalIdentifier": "bf1a2b3c-0002-4a7b-8c9d-0e1f2a3b4c5d",+ },+ ],+ "icon": "IconMail",+ "name": "All Post Cards",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "position": 0,+ "type": "TABLE",+ "universalIdentifier": "b1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "fields": [+ {+ "fieldMetadataUniversalIdentifier": "d2a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ "isVisible": true,+ "position": 0,+ "size": 200,+ "universalIdentifier": "bf1a2b3c-0003-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "fieldMetadataUniversalIdentifier": "d3a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ "isVisible": true,+ "position": 1,+ "size": 150,+ "universalIdentifier": "bf1a2b3c-0004-4a7b-8c9d-0e1f2a3b4c5d",+ },+ ],+ "icon": "IconUser",+ "name": "All Recipients",+ "objectUniversalIdentifier": "d1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",+ "position": 1,+ "type": "TABLE",+ "universalIdentifier": "b1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "fields": [+ {+ "fieldMetadataUniversalIdentifier": "e2a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "isVisible": true,+ "position": 0,+ "size": 200,+ "universalIdentifier": "fd959c6f-3465-4a3a-b7ad-3f4004fffc9a",+ },+ ],+ "icon": "IconLink",+ "name": "All Post Card Recipients",+ "objectUniversalIdentifier": "e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e",+ "position": 2,+ "type": "TABLE",+ "universalIdentifier": "b1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "fields": [+ {+ "fieldMetadataUniversalIdentifier": "58a0a314-d7ea-4865-9850-7fb84e72f30b",+ "isVisible": true,+ "position": 0,+ "size": 200,+ "universalIdentifier": "bf1a2b3c-0005-4a7b-8c9d-0e1f2a3b4c5d",+ },+ ],+ "groups": [+ {+ "fieldValue": "DRAFT",+ "isVisible": true,+ "position": 0,+ "universalIdentifier": "e9ed34f1-3c3d-41b1-869b-00aae0033d9c",+ },+ {+ "fieldValue": "SENT",+ "isVisible": true,+ "position": 1,+ "universalIdentifier": "19b1a3c1-53f0-4d32-b072-d645dac98e38",+ },+ {+ "fieldValue": "DELIVERED",+ "isVisible": true,+ "position": 2,+ "universalIdentifier": "f545cb5a-370d-423f-9b4e-278a9a465bdf",+ },+ {+ "fieldValue": "RETURNED",+ "isVisible": true,+ "position": 3,+ "universalIdentifier": "5d4c6d5f-af53-4cd0-a843-df38915561b2",+ },+ {+ "fieldValue": "LOST",+ "isVisible": true,+ "position": 4,+ "universalIdentifier": "5ebbd7dc-9939-4594-b2a0-519269b4531f",+ },+ ],+ "icon": "IconLayoutKanban",+ "mainGroupByFieldMetadataUniversalIdentifier": "87b675b8-dd8c-4448-b4ca-20e5a2234a1e",+ "name": "By Status",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "position": 1,+ "type": "KANBAN",+ "universalIdentifier": "b1a2b3c4-0004-4a7b-8c9d-0e1f2a3b4c5d",+ },+ {+ "calendarFieldMetadataUniversalIdentifier": "e06abe72-5b44-4e7f-93be-afc185a3c433",+ "calendarLayout": "MONTH",+ "fields": [+ {+ "fieldMetadataUniversalIdentifier": "58a0a314-d7ea-4865-9850-7fb84e72f30b",+ "isVisible": true,+ "position": 0,+ "size": 200,+ "universalIdentifier": "bf1a2b3c-0006-4a7b-8c9d-0e1f2a3b4c5d",+ },+ ],+ "icon": "IconCalendarEvent",+ "name": "By Delivery Date",+ "objectUniversalIdentifier": "54b589ca-eeed-4950-a176-358418b85c05",+ "position": 2,+ "type": "CALENDAR",+ "universalIdentifier": "b1a2b3c4-0005-4a7b-8c9d-0e1f2a3b4c5d",+ },+ ],+ "workflows": [],+ },+ "success": true,+ "warnings": [+ "\`defaultRoleUniversalIdentifier\` on defineApplication() is deprecated. Use defineApplicationRole() in your role file instead.",+ "Front component "root-component" declares no widgetAvailability, so it is not offered in any widget picker. Set widgetAvailability to let users add it to record pages or dashboards.",+ "Front component "test-component" declares no widgetAvailability, so it is not offered in any widget picker. Set widgetAvailability to let users add it to record pages or dashboards.",+ ""twenty-sdk" is listed under "dependencies" in package.json. It is a build-time only tool and should be moved to "devDependencies".",+ ""twenty-client-sdk" is listed under "dependencies" in package.json. It is provided at runtime by Twenty's injected SDK and should be moved to "devDependencies".",+ ],+}+`;++exports[`CLI manifest fixtures and worker transport > matches the manifest, file paths, errors and warnings for shared-dependencies-app 1`] = `+{+ "filePaths": {+ "agents": [],+ "application": [+ "application.config.ts",+ ],+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [],+ "frontComponents": [+ "src/counter.front-component.tsx",+ ],+ "indexes": [],+ "logicFunctions": [],+ "navigationMenuItems": [],+ "objects": [],+ "pageLayoutTabs": [],+ "pageLayoutWidgets": [],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [],+ "roles": [+ "my.role.ts",+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [],+ "viewFields": [],+ "views": [],+ "workflows": [],+ },+ "manifest": {+ "agents": [],+ "application": {+ "defaultRoleUniversalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000102",+ "description": "An app sharing dependencies across its front components",+ "displayName": "Shared Dependencies App",+ "frontComponentSharedDependencies": {+ "builtChecksum": null,+ "builtPath": "front-component-shared-dependencies.mjs",+ "dependencies": [+ "react",+ "react-dom/client",+ "react/jsx-runtime",+ ],+ },+ "galleryImages": [],+ "packageJsonChecksum": null,+ "requiredServerVersionRange": null,+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000101",+ "yarnLockChecksum": null,+ },+ "commandMenuItems": [],+ "connectionProviders": [],+ "fields": [],+ "frontComponents": [+ {+ "builtComponentChecksum": "",+ "builtComponentPath": "src/counter.front-component.mjs",+ "componentName": "Counter",+ "description": "A component relying on the shared react",+ "isHeadless": false,+ "name": "counter",+ "sourceComponentPath": "src/counter.front-component.tsx",+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000103",+ },+ ],+ "indexes": [],+ "logicFunctions": [],+ "navigationMenuItems": [],+ "objects": [],+ "pageLayoutTabs": [],+ "pageLayoutWidgets": [],+ "pageLayouts": [],+ "permissionFlags": [],+ "publicAssets": [],+ "roles": [+ {+ "canBeAssignedToAgents": false,+ "canBeAssignedToApiKeys": false,+ "canBeAssignedToUsers": true,+ "canDestroyAllObjectRecords": false,+ "canReadAllObjectRecords": true,+ "canSoftDeleteAllObjectRecords": false,+ "canUpdateAllObjectRecords": false,+ "canUpdateAllSettings": false,+ "description": "The default role of the shared dependencies app",+ "fieldPermissions": [],+ "label": "Shared dependencies app role",+ "objectPermissions": [],+ "permissionFlagUniversalIdentifiers": [],+ "rowLevelPermissionPredicateGroups": [],+ "rowLevelPermissionPredicates": [],+ "universalIdentifier": "e1e2e3e4-e5e6-4000-8000-000000000102",+ },+ ],+ "settingsMenuItems": [],+ "skills": [],+ "timelineActivityTypes": [],+ "viewFields": [],+ "views": [],+ "workflows": [],+ },+ "success": true,+ "warnings": [+ "\`defaultRoleUniversalIdentifier\` on defineApplication() is deprecated. Use defineApplicationRole() in your role file instead.",+ "Front component "counter" declares no widgetAvailability, so it is not offered in any widget picker. Set widgetAvailability to let users add it to record pages or dashboards.",+ ""twenty-sdk" is listed under "dependencies" in package.json. It is a build-time only tool and should be moved to "devDependencies".",+ ""twenty-client-sdk" is listed under "dependencies" in package.json. It is provided at runtime by Twenty's injected SDK and should be moved to "devDependencies".",+ ],+}+`;diff --git a/packages/twenty-cli/src/app/manifest/__tests__/manifest-parity.spec.ts b/packages/twenty-cli/src/app/manifest/__tests__/manifest-fixtures.spec.tssimilarity index 86%rename from packages/twenty-cli/src/app/manifest/__tests__/manifest-parity.spec.tsrename to packages/twenty-cli/src/app/manifest/__tests__/manifest-fixtures.spec.tsindex 2539619d33c..02912074e99 100644--- a/packages/twenty-cli/src/app/manifest/__tests__/manifest-parity.spec.ts+++ b/packages/twenty-cli/src/app/manifest/__tests__/manifest-fixtures.spec.ts@@ -13,7 +13,7 @@ import { tmpdir } from 'node:os';import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';-import { build as bundle, stop } from 'esbuild';+import { stop } from 'esbuild';import {afterAll,afterEach,@@ -25,12 +25,11 @@ import {} from 'vitest';import { buildTestAppWorker } from '@/app/__tests__/utils/build-test-app-worker';-import { SORTED_GLOB_PLUGIN } from '@/app/__tests__/utils/sorted-glob-plugin';import { buildAndValidateManifest } from '@/app/manifest/build-and-validate-manifest';import { buildManifest } from '@/app/manifest/manifest-build';import { createAppProject } from '@/app/create-app-project';import { runAppWorker } from '@/app/run-app-worker';-import { type compileApplicationTranslations } from '@/app/translations/compile-application-translations';+import { compileApplicationTranslations } from '@/app/translations/compile-application-translations';const launch = vi.hoisted(() => ({ modulePath: '', execArgv: [] as string[] }));@@ -57,17 +56,10 @@ const FIXTURES = ['invalid-app',];-type SdkReference = {- buildManifest: typeof buildManifest;- buildAndValidateManifest: typeof buildAndValidateManifest;- compileApplicationTranslations: typeof compileApplicationTranslations;-};-const json = (value: unknown): unknown => JSON.parse(JSON.stringify(value));-describe('CLI manifest parity with the repository SDK', () => {+describe('CLI manifest fixtures and worker transport', () => {let root: string;- let sdk: SdkReference;const copyFixture = async (name: string) => {const appPath = await mkdtemp(join(root, `${name}-`));@@ -85,11 +77,11 @@ describe('CLI manifest parity with the repository SDK', () => {};const compareManifest = async (appPath: string) => {- const expected = await sdk- .buildAndValidateManifest(appPath)- .catch((error: unknown) => ({+ const expected = await buildAndValidateManifest(appPath).catch(+ (error: unknown) => ({thrown: error instanceof Error ? error.message : String(error),- }));+ }),+ );if ('thrown' in expected) {await expect(buildAndValidateManifest(appPath)).rejects.toThrow(@@ -108,16 +100,9 @@ describe('CLI manifest parity with the repository SDK', () => {return { success: false as const, errors: [expected.thrown] };}- const actual = await buildAndValidateManifest(appPath);-- expect(json(actual)).toEqual(json(expected));- expect(json(await buildManifest(appPath))).toEqual(- json(await sdk.buildManifest(appPath)),- );-const warnings: string[] = [];const translations = expected.success- ? await sdk.compileApplicationTranslations({+ ? await compileApplicationTranslations({appPath,onWarning: (message) => warnings.push(message),})@@ -160,7 +145,7 @@ describe('CLI manifest parity with the repository SDK', () => {),);- return actual;+ return expected;};beforeAll(async () => {@@ -223,27 +208,6 @@ describe('CLI manifest parity with the repository SDK', () => {createRequire(join(root, 'package.json')).resolve('twenty-sdk/build'),).toThrow();- const oraclePath = join(root, 'sdk-reference.cjs');- const sdkSource = join(sourceSdk, 'src');-- await bundle({- stdin: {- contents: `export { buildManifest } from './cli/utilities/build/manifest/manifest-build';-export { buildAndValidateManifest } from './cli/utilities/build/manifest/build-and-validate-manifest';-export { compileApplicationTranslations } from './cli/utilities/translations/compile-application-translations';`,- resolveDir: sdkSource,- },- outfile: oraclePath,- alias: { '@': sdkSource },- bundle: true,- packages: 'external',- platform: 'node',- format: 'cjs',- target: 'node24',- plugins: [SORTED_GLOB_PLUGIN],- });- sdk = createRequire(import.meta.url)(oraclePath) as SdkReference;-await buildTestAppWorker(join(root, 'cli'));launch.modulePath = join(root, 'cli/app-worker.cjs');}, 60000);@@ -266,9 +230,13 @@ export { compileApplicationTranslations } from './cli/utilities/translations/comit.each(FIXTURES)('matches the manifest, file paths, errors and warnings for %s',async (name) => {- const result = await compareManifest(await copyFixture(name));+ const appPath = await copyFixture(name);+ const result = await compareManifest(appPath);expect(result.success).toBe(name !== 'invalid-app');+ expect(+ JSON.parse(JSON.stringify(result).replaceAll(appPath, '<app>')),+ ).toMatchSnapshot();},60000,);diff --git a/packages/twenty-cli/src/app/render-app-template.ts b/packages/twenty-cli/src/app/render-app-template.tsindex fac71b14032..7feeeff2b23 100644--- a/packages/twenty-cli/src/app/render-app-template.ts+++ b/packages/twenty-cli/src/app/render-app-template.ts@@ -33,13 +33,20 @@ export const renderAppTemplate = async ({await cp(join(appDirectory, 'AGENTS.md'), join(appDirectory, 'CLAUDE.md'));- const workflowPath = join(appDirectory, '.github', 'workflows', 'ci.yml');- const workflow = (await readFile(workflowPath, 'utf8')).replace(- 'CLI-VERSION-TO-BE-GENERATED',- CLI_VERSION,- );+ for (const workflowName of ['ci.yml', 'cd.yml', 'publish.yml']) {+ const workflowPath = join(+ appDirectory,+ '.github',+ 'workflows',+ workflowName,+ );+ const workflow = (await readFile(workflowPath, 'utf8')).replaceAll(+ 'CLI-VERSION-TO-BE-GENERATED',+ CLI_VERSION,+ );- await writeFile(workflowPath, workflow);+ await writeFile(workflowPath, workflow);+ }const identifiersPath = join(appDirectory,diff --git a/packages/twenty-cli/src/app/snapshots/__tests__/snapshot-parity.spec.ts b/packages/twenty-cli/src/app/snapshots/__tests__/snapshot-artifacts.spec.tssimilarity index 91%rename from packages/twenty-cli/src/app/snapshots/__tests__/snapshot-parity.spec.tsrename to packages/twenty-cli/src/app/snapshots/__tests__/snapshot-artifacts.spec.tsindex 0c4c74fc5e1..934cfcb73b1 100644--- a/packages/twenty-cli/src/app/snapshots/__tests__/snapshot-parity.spec.ts+++ b/packages/twenty-cli/src/app/snapshots/__tests__/snapshot-artifacts.spec.ts@@ -15,12 +15,11 @@ import { tmpdir } from 'node:os';import { dirname, join, resolve } from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';-import { build as bundle, stop } from 'esbuild';+import { stop } from 'esbuild';import { isPlainObject } from 'twenty-shared/utils';import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';import { buildTestAppWorker } from '@/app/__tests__/utils/build-test-app-worker';-import { SORTED_GLOB_PLUGIN } from '@/app/__tests__/utils/sorted-glob-plugin';import { createAppProject } from '@/app/create-app-project';import { pathExists } from '@/app/fs-utils';import { runAppWorker } from '@/app/run-app-worker';@@ -136,9 +135,8 @@ const comparableSnapshot = (build: ToolingBuild) => {};};-describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () => {+describe('CLI snapshots produce repeatable artifacts', () => {let root: string;- let sdkEntryPath: string;const copyFixture = async (name: string) => {const appPath = await mkdtemp(join(root, `${name}-`));@@ -154,24 +152,18 @@ describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () =return appPath;};- const buildSdkSnapshot = async (- appPath: string,- useHeldSnapshot?: Parameters<typeof runAppWorker>[0]['useHeldSnapshot'],- ) => {- launch.modulePath = join(root, 'reference/app-worker.cjs');- try {- return await runAppWorker({- request: { type: 'bundleSnapshot', appPath, holdSnapshot: true },- signal: new AbortController().signal,- useHeldSnapshot: async (snapshot) => {- launch.modulePath = join(root, 'cli/app-worker.cjs');- await useHeldSnapshot?.(snapshot);- },- });- } finally {- launch.modulePath = join(root, 'cli/app-worker.cjs');- }- };+ const buildRepeatedSnapshot = ({+ appPath,+ useHeldSnapshot,+ }: {+ appPath: string;+ useHeldSnapshot: Parameters<typeof runAppWorker>[0]['useHeldSnapshot'];+ }) =>+ runAppWorker({+ request: { type: 'bundleSnapshot', appPath, holdSnapshot: true },+ signal: new AbortController().signal,+ useHeldSnapshot,+ });const compareSnapshot = async (appPath: string) => {const compareBuild = async ({ result }: { result: unknown }) => {@@ -290,12 +282,15 @@ describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () =(response.result as { diagnostics: unknown }).diagnostics,).toEqual(json(expected.diagnostics));}- expect(await readdir(join(appPath, '.twenty/cli/snapshots'))).toEqual([]);};- const reference = await buildSdkSnapshot(appPath, compareBuild);+ const reference = await buildRepeatedSnapshot({+ appPath,+ useHeldSnapshot: compareBuild,+ });if (!reference.isSnapshotHeld) {await compareBuild(reference);}+ expect(await readdir(join(appPath, '.twenty/cli/snapshots'))).toEqual([]);return reference.result as Awaited<ReturnType<typeof buildSnapshot>>;};beforeAll(async () => {@@ -362,32 +357,6 @@ describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () =createRequire(join(root, 'package.json')).resolve('twenty-sdk/build'),).toThrow();- sdkEntryPath = join(root, 'sdk-reference.cjs');- const sdkSource = join(sourceSdk, 'src');-- await bundle({- stdin: {- contents: `export { buildSnapshot as buildSourceSnapshot, releaseSnapshot as releaseSourceSnapshot } from './application-build/build-snapshot';`,- resolveDir: sdkSource,- },- outfile: sdkEntryPath,- alias: { '@': sdkSource },- bundle: true,- packages: 'external',- platform: 'node',- format: 'cjs',- target: 'node24',- plugins: [SORTED_GLOB_PLUGIN],- });-- await mkdir(join(root, 'assets'));- await cp(- join(sdkSource, 'cli/utilities/build/cover/assets/halftone-backdrop.png'),- join(root, 'assets/halftone-backdrop.png'),- );- await buildTestAppWorker(join(root, 'reference'), {- aliases: { '@/app/worker/build-source-snapshot': sdkEntryPath },- });await buildTestAppWorker(join(root, 'cli'));launch.modulePath = join(root, 'cli/app-worker.cjs');}, 60000);@@ -405,7 +374,7 @@ describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () =).toEqual([...FIXTURES].sort());});it.each(FIXTURES)(- 'preserves SDK manifest and non-frontend bytes, validates all artifact hashes for %s',+ 'preserves manifest and non-frontend bytes, validates all artifact hashes for %s',async (name) => {const result = await compareSnapshot(await copyFixture(name));expect(result.success, JSON.stringify(result)).toBe(@@ -493,7 +462,7 @@ describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () =await cp(join(REPOSITORY_ROOT,- 'packages/twenty-sdk/src/cli/utilities/build/cover/assets/halftone-backdrop.png',+ 'packages/twenty-cli/src/app/bundles/cover/assets/halftone-backdrop.png',),join(appPath, 'public/logo.png'),);@@ -639,12 +608,10 @@ describe('CLI snapshots preserve SDK manifests and non-frontend artifacts', () =config.references = [{ path: './referenced' }];await writeFile(configPath, JSON.stringify(config));}- const expected = (await buildSdkSnapshot(appPath)).result;const response = await runAppWorker({request: { type: 'bundleSnapshot', appPath, holdSnapshot: true },signal: new AbortController().signal,});- expect(response.result).toEqual(json(expected));expect(response.result).toMatchObject({success: false,error: { code: 'TYPECHECK_FAILED' },diff --git a/packages/twenty-cli/src/app/typecheck/__tests__/typecheck-application.spec.ts b/packages/twenty-cli/src/app/typecheck/__tests__/typecheck-application.spec.tsindex 386f61c83d0..d91c4442a8e 100644--- a/packages/twenty-cli/src/app/typecheck/__tests__/typecheck-application.spec.ts+++ b/packages/twenty-cli/src/app/typecheck/__tests__/typecheck-application.spec.ts@@ -12,7 +12,7 @@ import { tmpdir } from 'node:os';import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';-import { build, stop } from 'esbuild';+import { stop } from 'esbuild';import {afterAll,afterEach,@@ -41,10 +41,9 @@ const REPOSITORY_ROOT = fileURLToPath(const require = createRequire(import.meta.url);const compilerDirectory = dirname(require.resolve('typescript/package.json'));-describe('CLI typecheck matches the SDK with the same compiler', () => {+describe('CLI typecheck uses the application compiler', () => {let appPath: string;let referenceDirectory: string;- let sdk: { typecheckApplication: typeof typecheckApplication };const checkWithWorker = async () => {const response = await runAppWorker({@@ -58,12 +57,10 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {});};- const checkWithParity = async () => {- const expected = await sdk.typecheckApplication({ appPath });+ const checkDirectAndWorker = async () => {const direct = await typecheckApplication({ appPath });const worker = await checkWithWorker();- expect(direct).toEqual(expected);- expect(worker).toEqual(expected);+ expect(worker).toEqual(direct);return worker;};@@ -78,21 +75,6 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {join(referenceDirectory, 'node_modules', name),);}- const sdkSource = join(REPOSITORY_ROOT, 'packages/twenty-sdk/src');- const entry = join(referenceDirectory, 'sdk-reference.cjs');- await build({- entryPoints: [- join(sdkSource, 'application-build/typecheck-application.ts'),- ],- outfile: entry,- alias: { '@': sdkSource },- bundle: true,- packages: 'external',- platform: 'node',- format: 'cjs',- target: 'node24',- });- sdk = require(entry) as typeof sdk;await buildTestAppWorker(join(referenceDirectory, 'cli'));launch.modulePath = join(referenceDirectory, 'cli/app-worker.cjs');}, 60000);@@ -122,7 +104,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {});it('checks valid code without emitting files or requiring an SDK', async () => {- expect(await checkWithParity()).toEqual({+ expect(await checkDirectAndWorker()).toEqual({success: true,data: null,diagnostics: [],@@ -139,7 +121,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {join(appPath, 'example.ts'),'export const broken: number = "bad";',);- expect(await checkWithParity()).toMatchObject({+ expect(await checkDirectAndWorker()).toMatchObject({success: false,error: { code: 'TYPECHECK_FAILED' },diagnostics: [@@ -156,7 +138,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {it('fails when tsconfig.json is missing', async () => {await rm(join(appPath, 'tsconfig.json'));- expect(await checkWithParity()).toMatchObject({+ expect(await checkDirectAndWorker()).toMatchObject({success: false,error: { code: 'TYPECHECK_FAILED' },diagnostics: [{ severity: 'error', code: 'TS5083' }],@@ -174,7 +156,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {['no matching files', { include: ['missing/**/*.ts'] }, 'TS18003'],])('fails on %s', async (_name, config, code) => {await writeFile(join(appPath, 'tsconfig.json'), JSON.stringify(config));- expect(await checkWithParity()).toMatchObject({+ expect(await checkDirectAndWorker()).toMatchObject({success: false,error: { code: 'TYPECHECK_FAILED' },diagnostics: expect.arrayContaining([@@ -185,7 +167,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {it('reports invalid JSON configuration', async () => {await writeFile(join(appPath, 'tsconfig.json'), '{ "compilerOptions": ');- expect(await checkWithParity()).toMatchObject({+ expect(await checkDirectAndWorker()).toMatchObject({success: false,error: { code: 'TYPECHECK_FAILED' },diagnostics: [expect.objectContaining({ severity: 'error' })],@@ -213,7 +195,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {references: [{ path: './referenced' }],}),);- const result = await checkWithParity();+ const result = await checkDirectAndWorker();expect(result).toMatchObject({success: false,error: { code: 'TYPECHECK_FAILED' },@@ -302,7 +284,7 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {}),);await writeFile(join(appPath, 'example.ts'), 'export const value = 1;');- expect(await checkWithParity()).toMatchObject({ success: true });+ expect(await checkDirectAndWorker()).toMatchObject({ success: true });} finally {appPath = workspacePath;}@@ -319,24 +301,24 @@ describe('CLI typecheck matches the SDK with the same compiler', () => {expect(await checkWithWorker()).toMatchObject({ success: true });await rm(join(appPath, 'node_modules/typescript'));await mkdir(join(appPath, 'node_modules/typescript'));- const sdkRequire = createRequire(- join(REPOSITORY_ROOT, 'packages/twenty-sdk/package.json'),- );- const legacyCompilerPath = sdkRequire.resolve('@ts-morph/common');await writeFile(join(appPath, 'node_modules/typescript/package.json'),JSON.stringify({ name: 'typescript', main: 'index.cjs' }),);await writeFile(join(appPath, 'node_modules/typescript/index.cjs'),- `module.exports = require(${JSON.stringify(legacyCompilerPath)}).ts;`,+ `const compiler = require(${JSON.stringify(require.resolve('typescript'))});+ module.exports = { ...compiler, getPreEmitDiagnostics() {+ return [{ category: compiler.DiagnosticCategory.Error, code: 99999,+ messageText: 'Diagnostic from the application compiler' }];+ } };`,);expect(await checkWithWorker()).toMatchObject({success: false,diagnostics: expect.arrayContaining([expect.objectContaining({- code: 'TS6046',- message: expect.stringContaining('--module'),+ code: 'TS99999',+ message: 'Diagnostic from the application compiler',}),]),});diff --git a/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts b/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.tsindex c6ce2f81e56..9e8c63f4468 100644--- a/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts+++ b/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts@@ -187,6 +187,22 @@ describe('app init', () => {);});+ it('pins the generating CLI version in deployment and publishing workflows', async () => {+ const result = await run(['my-app']);++ expect(result.exitCode, result.stderr).toBe(0);++ for (const workflowName of ['cd.yml', 'publish.yml']) {+ const workflow = await readFile(+ join(workDirectory, 'my-app', '.github', 'workflows', workflowName),+ 'utf8',+ );++ expect(workflow).toContain(CLI_VERSION);+ expect(workflow).not.toContain('TO-BE-GENERATED');+ }+ });+it('returns the app, its pins and the next steps as JSON, without a login step when a workspace is set', async () => {vi.stubEnv('TWENTY_API_URL', 'https://crm.example.com');vi.stubEnv('TWENTY_API_KEY', 'test-key');diff --git a/packages/twenty-client-sdk/src/generate/__tests__/generated-client-query.test.ts b/packages/twenty-client-sdk/src/generate/__tests__/generated-client-query.test.tsindex c1b9b5cfd46..e168de4402a 100644--- a/packages/twenty-client-sdk/src/generate/__tests__/generated-client-query.test.ts+++ b/packages/twenty-client-sdk/src/generate/__tests__/generated-client-query.test.ts@@ -27,6 +27,7 @@ type Query {type Mutation {createPerson(name: String!): Person+ echoJson(value: JSON): JSONcreateCallRecording(data: CallRecordingCreateInput!): String}@@ -164,6 +165,24 @@ const inputs = [expect(body.query).toMatch(/createPerson/);});+ it('preserves JSON array payloads', async () => {+ const transcript = [+ { participant: { name: 'Ada' }, words: [{ text: 'Hello' }] },+ ];+ const fetchMock = vi.fn<typeof globalThis.fetch>(async () =>+ jsonResponse({ data: { echoJson: transcript } }),+ );+ const client = createClient({+ url: 'https://example.test/graphql',+ fetch: fetchMock,+ });+ expect(+ await client.mutation({ echoJson: { __args: { value: transcript } } }),+ ).toEqual({ echoJson: transcript });+ const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));+ expect(Object.values(body.variables)).toContainEqual(transcript);+ });+it('throws when the API responds with GraphQL errors', async () => {const fetchMock = vi.fn(async () =>jsonResponse({ errors: [{ message: 'Not authorized' }], data: null }),diff --git a/packages/twenty-companion/README.md b/packages/twenty-companion/README.mdindex b2e2f4ee23d..852b94c1c1d 100644--- a/packages/twenty-companion/README.md+++ b/packages/twenty-companion/README.md@@ -108,7 +108,7 @@ The package command verifies Recall's executable is outside the ASAR archive. ThThe backend is [Desktop Recorder](../twenty-apps/public/companion/README.md), an independently installable Twenty application. It owns `/companion/desktop`, the `companionSession` ownership field, import/recovery functions, its summarizer agent, and Recall credentials. Follow its [setup instructions](../twenty-apps/public/companion/SETUP.md). Call Recorder is optional.-The desktop reuses the CLI OAuth client and browser sign-in flow used by `twenty remote:add`, with PKCE and a local callback. Tokens stay in the desktop's secure store. After sign-in, the desktop checks the backend and offers installation if it is missing. An administrator installs the integration in each target workspace. Existing completed desktop recordings can be transferred using the integration's one-time migration script without replacing their media or record IDs.+The desktop reuses the CLI OAuth client and browser sign-in flow used by `twenty auth login`, with PKCE and a local callback. Tokens stay in the desktop's secure store. After sign-in, the desktop checks the backend and offers installation if it is missing. An administrator installs the integration in each target workspace. Existing completed desktop recordings can be transferred using the integration's one-time migration script without replacing their media or record IDs.## Code structure@@ -143,7 +143,7 @@ Google or Microsoft calendar connection.From `packages/twenty-apps/public/companion`:```sh-yarn twenty -r companion-local apply+twenty app apply --remote companion-local```The `companion-local` remote targets port 2021. It is separate from the normaldiff --git a/packages/twenty-docs/developers/extend/apps/config/install-hooks.mdx b/packages/twenty-docs/developers/extend/apps/config/install-hooks.mdxindex ad722d26042..903f48987ae 100644--- a/packages/twenty-docs/developers/extend/apps/config/install-hooks.mdx+++ b/packages/twenty-docs/developers/extend/apps/config/install-hooks.mdx@@ -1,7 +1,7 @@---title: Install Hooksdescription: Run logic during the install, upgrade, or uninstall lifecycle — seed data, back up records, validate the upgrade, clean up external resources.-icon: "wrench"+icon: 'wrench'---Install hooks are special logic functions that run during the install, upgrade, or uninstall lifecycle. They share the same handler runtime as regular [logic functions](/developers/extend/apps/logic/logic-functions), but they're declared with their own define functions and live outside the normal trigger model (HTTP, cron, database events). Install hooks receive an `InstallPayload` (`{ previousVersion?: string; newVersion: string }` — `previousVersion` is `undefined` on a fresh install); the uninstall hook receives an `UninstallPayload` (`{ version?: string }` — the version being removed).@@ -21,23 +21,23 @@ Each app may define **at most one** of each hook (pre-install, post-install, uni## At a glance-| | `definePreInstallLogicFunction` | `definePostInstallLogicFunction` |-|---|---|---|-| Runs | Before the metadata migration — the **previous** schema and data are still intact | After the migration and SDK generation — the **new** schema is in place |-| Execution | Always synchronous; blocks the install | Async by default (queued, 3 retries); sync opt-in via `shouldRunSynchronously: true` |-| On failure | Install is **aborted** before any schema change | Async: retried up to 3 times. Sync: caller receives `POST_INSTALL_ERROR` (schema changes are **not** rolled back) |-| Typical use | Back up or fix data a migration would lose; refuse a risky upgrade by throwing | Seed default data, configure the workspace, register external resources |+| | `definePreInstallLogicFunction` | `definePostInstallLogicFunction` |+| ----------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |+| Runs | Before the metadata migration — the **previous** schema and data are still intact | After the migration and SDK generation — the **new** schema is in place |+| Execution | Always synchronous; blocks the install | Async by default (queued, 3 retries); sync opt-in via `shouldRunSynchronously: true` |+| On failure | Install is **aborted** before any schema change | Async: retried up to 3 times. Sync: caller receives `POST_INSTALL_ERROR` (schema changes are **not** rolled back) |+| Typical use | Back up or fix data a migration would lose; refuse a risky upgrade by throwing | Seed default data, configure the workspace, register external resources |**Rule of thumb:** default to post-install. Only reach for pre-install when the migration itself is destructive and you need to intercept the previous state before it is gone.-| You want to... | Use |-|---|---|-| Seed data, configure the workspace, register external resources | `post-install` |-| Long-running work that shouldn't block the install response | `post-install` (default async mode, with worker retries) |-| Fast setup the caller relies on immediately after the install returns | `post-install` with `shouldRunSynchronously: true` |-| Read or back up data that the upcoming migration would lose | `pre-install` |-| Reject an upgrade that would corrupt existing data | `pre-install` (throw from the handler) |-| Reconciliation on every upgrade | Either hook with `shouldRunOnVersionUpgrade: true` |+| You want to... | Use |+| --------------------------------------------------------------------- | -------------------------------------------------------- |+| Seed data, configure the workspace, register external resources | `post-install` |+| Long-running work that shouldn't block the install response | `post-install` (default async mode, with worker retries) |+| Fast setup the caller relies on immediately after the install returns | `post-install` with `shouldRunSynchronously: true` |+| Read or back up data that the upcoming migration would lose | `pre-install` |+| Reject an upgrade that would corrupt existing data | `pre-install` (throw from the handler) |+| Reconciliation on every upgrade | Either hook with `shouldRunOnVersionUpgrade: true` |## Behavior shared by both hooks@@ -47,11 +47,11 @@ Each app may define **at most one** of each hook (pre-install, post-install, uni- The usual logic-function environment (`APPLICATION_ID`, `APP_ACCESS_TOKEN`, `API_URL`) is injected, so you can call the Twenty API with your app's token.- The hook is attached to the application manifest automatically at build time (`preInstallLogicFunction` / `postInstallLogicFunction`) — nothing to reference in [`defineApplication()`](/developers/extend/apps/config/application).- The default `timeoutSeconds` is 300 to allow longer setup tasks like data seeding.-- **Not executed in dev mode**: `yarn twenty dev` skips the install flow and syncs files directly, so hooks never run there. Trigger them manually instead:+- **Not executed in dev mode**: `twenty app dev` skips the install flow and syncs files directly, so hooks never run there. Trigger them manually instead:```bash filename="Terminal"-yarn twenty dev:function:exec --postInstall-yarn twenty dev:function:exec --preInstall+twenty app exec --post-install+twenty app exec --pre-install```<AccordionGroup>@@ -60,7 +60,10 @@ yarn twenty dev:function:exec --preInstallRuns once your app has finished installing: metadata synchronized, SDK client generated, new schema queryable. Example — seed a default record on fresh installs:```ts src/logic-functions/post-install.ts-import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';+import {+ definePostInstallLogicFunction,+ type InstallPayload,+} from 'twenty-sdk/define';import { CoreApiClient } from 'twenty-client-sdk/core';const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {@@ -69,7 +72,9 @@ const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {const client = new CoreApiClient();await client.mutation({createPostCard: {- __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },+ __args: {+ data: { name: 'Welcome to Postcard', content: 'Your first card!' },+ },id: true,},});@@ -88,7 +93,7 @@ export default definePostInstallLogicFunction({The `shouldRunSynchronously` flag controls the execution model:-- `false` *(default)* — enqueued on the message queue (`retryLimit: 3`) and run by a worker. The install response returns as soon as the job is enqueued. **Use for long-running work** — seeding large datasets, slow third-party APIs.+- `false` _(default)_ — enqueued on the message queue (`retryLimit: 3`) and run by a worker. The install response returns as soon as the job is enqueued. **Use for long-running work** — seeding large datasets, slow third-party APIs.- `true` — executed inline during the install flow. The install request blocks until the handler finishes; a thrown error surfaces as `POST_INSTALL_ERROR` to the caller (no retries). **Use for fast, must-complete-before-response work.** The migration has already been applied at this point, so a failure does not roll back schema changes — it only surfaces the error.</Accordion>@@ -101,10 +106,16 @@ Pre-install is always **synchronous** and blocks the install. If the handler thrExample — copy a legacy field's values before the migration drops it:```ts src/logic-functions/pre-install.ts-import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';+import {+ definePreInstallLogicFunction,+ type InstallPayload,+} from 'twenty-sdk/define';import { CoreApiClient } from 'twenty-client-sdk/core';-const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {+const handler = async ({+ previousVersion,+ newVersion,+}: InstallPayload): Promise<void> => {// Only the 1.x → 2.x upgrade drops the legacy `notes` field.if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {return;@@ -133,7 +144,8 @@ const handler = async ({ previousVersion, newVersion }: InstallPayload): Promiseexport default definePreInstallLogicFunction({universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',name: 'pre-install',- description: 'Backs up legacy notes into description before the v2 migration.',+ description:+ 'Backs up legacy notes into description before the v2 migration.',timeoutSeconds: 300,shouldRunOnVersionUpgrade: true,handler,@@ -156,11 +168,14 @@ Notes:- Like the install hooks, it is **not executed in dev mode** — trigger it manually instead:```bash filename="Terminal"-yarn twenty dev:function:exec --uninstall+twenty app exec --uninstall-hook``````ts src/logic-functions/uninstall.ts-import { defineUninstallLogicFunction, type UninstallPayload } from 'twenty-sdk/define';+import {+ defineUninstallLogicFunction,+ type UninstallPayload,+} from 'twenty-sdk/define';import { CoreApiClient } from 'twenty-client-sdk/core';const handler = async (_payload: UninstallPayload): Promise<void> => {diff --git a/packages/twenty-docs/developers/extend/apps/config/public-assets.mdx b/packages/twenty-docs/developers/extend/apps/config/public-assets.mdxindex 049e2d13cd3..93649620666 100644--- a/packages/twenty-docs/developers/extend/apps/config/public-assets.mdx+++ b/packages/twenty-docs/developers/extend/apps/config/public-assets.mdx@@ -1,7 +1,7 @@---title: Public Assetsdescription: Ship static files — images, icons, fonts — alongside your app via the public/ folder.-icon: "folder-open"+icon: 'folder-open'---The `public/` folder at the root of your app holds static files — images, icons, fonts, or any other assets your app needs at runtime. These files are automatically included in builds, synced during dev mode, and uploaded to the server.@@ -13,7 +13,7 @@ Files placed in `public/` are:- **Available in logic functions** — reference asset URLs in emails, API responses, or any server-side logic.- **Used for marketplace metadata** — the `logo` and `galleryImages` fields in `defineApplication()` reference files from this folder (e.g., `public/logo.png`). These are displayed in the marketplace when your app is published. External absolute URLs are ignored for these fields — bundle the images in `public/` instead. Each image must not exceed 10 MB.- **Auto-synced in dev mode** — when you add, update, or delete a file in `public/`, it is synced to the server automatically. No restart needed.-- **Included in builds** — `yarn twenty dev:build` bundles all public assets into the distribution output.+- **Included in builds** — `twenty app build` bundles all public assets into the distribution output.## Accessing public assets with `getPublicAssetUrl`diff --git a/packages/twenty-docs/developers/extend/apps/data/objects.mdx b/packages/twenty-docs/developers/extend/apps/data/objects.mdxindex 55a2ef3ef63..06d7b0d0c4f 100644--- a/packages/twenty-docs/developers/extend/apps/data/objects.mdx+++ b/packages/twenty-docs/developers/extend/apps/data/objects.mdx@@ -1,7 +1,7 @@---title: Objectsdescription: Declare new record types — custom tables with their own fields — using defineObject.-icon: "table"+icon: 'table'---Custom **objects** are new record types your app adds to a workspace — Post Card, Invoice, Subscription, anything specific to your domain. Each object declares its schema (fields, relations, default values) and a stable universal identifier that survives across syncs and deploys.@@ -55,10 +55,30 @@ export default defineObject({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' },+ {+ 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',+ },],},{@@ -96,25 +116,30 @@ export default defineObject({- `isSearchable: true`, on a field, includes its values in the object's full-text search (global search and the command menu). It requires the object itself to be searchable and a text-compatible field type. An omitted value means not searchable, except for the object's label identifier field, which is always searchable and cannot be opted out. Each sync enforces the declared state, so a field toggled searchable from Settings reverts on your app's next sync unless the manifest declares it.- `isAuditLogged: false`, on a field, keeps its changes out of the record timeline. It defaults to `true`, except on a `POSITION` field, whose changes render blank in the timeline and are never logged. Set it on fields your app rewrites on a schedule, such as a last-contact timestamp or a rollup relation, so each sync does not add an activity row to every record it touches. An update whose whole diff is made of non audit logged fields produces no timeline activity at all. Like `isSearchable`, each sync enforces the declared state.- Inline fields defined here do **not** need an `objectUniversalIdentifier` — it's inherited from the parent object. Use [`defineField()`](/developers/extend/apps/data/extending-objects) to add fields to objects you don't own.-- You can scaffold new objects with `yarn twenty dev:add object`, which guides you through naming, fields, and relationships. See [Architecture → Scaffolding entities](/developers/extend/apps/getting-started/scaffolding).+- You can scaffold new objects with `twenty app add object`, which guides you through naming, fields, and relationships. See [Architecture → Scaffolding entities](/developers/extend/apps/getting-started/scaffolding).<Note>-**Base fields are added automatically.** When you define a custom object, Twenty creates standard fields like `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and `deletedAt` for you. You don't need to declare them in your `fields` array — only your custom fields. You can override a default field by declaring one with the same name, but this is rarely a good idea.+ **Base fields are added automatically.** When you define a custom object,+ Twenty creates standard fields like `id`, `name`, `createdAt`, `updatedAt`,+ `createdBy`, `updatedBy`, and `deletedAt` for you. You don't need to declare+ them in your `fields` array — only your custom fields. You can override a+ default field by declaring one with the same name, but this is rarely a good+ idea.</Note>## Field typesThe full set of `FieldType` values, exported from `twenty-sdk/define`:-| Category | Types |-|----------|-------|-| Text | `TEXT`, `RICH_TEXT`, `ARRAY` (of strings), `RAW_JSON` |-| Numeric | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (arbitrary precision), `RATING`, `POSITION` |-| Dates | `DATE`, `DATE_TIME` |-| Choice | `BOOLEAN`, `SELECT`, `MULTI_SELECT` |-| Composite | `FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS` (`universalSettings.type`: `'url'` (default) / `'domain'` — a domain field stores the bare host, so `https://www.acme.com/careers` is written as `acme.com`, and a value that is not a host is rejected), `CURRENCY`, `ACTOR`, `FILES` |-| Identifiers & relations | `UUID`, `RELATION`, `MORPH_RELATION` (see [Relations](/developers/extend/apps/data/relations)) |-| System | `TS_VECTOR` (full-text search vector, managed by the server) |+| Category | Types |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Text | `TEXT`, `RICH_TEXT`, `ARRAY` (of strings), `RAW_JSON` |+| Numeric | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (arbitrary precision), `RATING`, `POSITION` |+| Dates | `DATE`, `DATE_TIME` |+| Choice | `BOOLEAN`, `SELECT`, `MULTI_SELECT` |+| Composite | `FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS` (`universalSettings.type`: `'url'` (default) / `'domain'` — a domain field stores the bare host, so `https://www.acme.com/careers` is written as `acme.com`, and a value that is not a host is rejected), `CURRENCY`, `ACTOR`, `FILES` |+| Identifiers & relations | `UUID`, `RELATION`, `MORPH_RELATION` (see [Relations](/developers/extend/apps/data/relations)) |+| System | `TS_VECTOR` (full-text search vector, managed by the server) |Composite types store multiple sub-fields (e.g. `FULL_NAME` = first + last name; `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` and `MULTI_SELECT` require an `options` array as in the example above.@@ -144,7 +169,12 @@ The same convention applies to string sub-fields of composite defaults (e.g. `{Changes to `isNullable` are applied on every sync, including syncs that update an existing field — so you can flip a field's nullability by editing the manifest and re-syncing.<Note>-**Making an existing field non-nullable requires a default value.** When you change a field to `isNullable: false`, you must also provide a non-null `defaultValue`. The default backfills any existing `NULL` rows before the `NOT NULL` constraint is applied; without it the sync fails with `Default value cannot be null for non-nullable fields`. Relation fields and `TS_VECTOR` fields are always nullable, so `isNullable` has no effect on them.+ **Making an existing field non-nullable requires a default value.** When you+ change a field to `isNullable: false`, you must also provide a non-null+ `defaultValue`. The default backfills any existing `NULL` rows before the `NOT+ NULL` constraint is applied; without it the sync fails with `Default value+ cannot be null for non-nullable fields`. Relation fields and `TS_VECTOR`+ fields are always nullable, so `isNullable` has no effect on them.</Note>```tsdiff --git a/packages/twenty-docs/developers/extend/apps/data/timeline-activity-types.mdx b/packages/twenty-docs/developers/extend/apps/data/timeline-activity-types.mdxindex 12a9c3737ba..88f7a7ecd18 100644--- a/packages/twenty-docs/developers/extend/apps/data/timeline-activity-types.mdx+++ b/packages/twenty-docs/developers/extend/apps/data/timeline-activity-types.mdx@@ -7,16 +7,11 @@ icon: 'clock-rotate-left'A timeline activity type defines the stable vocabulary for an event shown in a record's timeline. Standard objects and app objects use the same contract: a type has a label and icon, can optionally declare when it is emitted, and can optionally render through one of your app's [front components](/developers/extend/apps/layout/front-components).<Note>- Timeline activity types are in beta, the API can evolve while we learn from app developers' use cases.+ Timeline activity types are in beta, the API can evolve while we learn from+ app developers' use cases.</Note>-Create one with the scaffolder:--```bash filename="Terminal"-yarn twenty dev:add timelineActivityType-```--Or define it directly:+Define a timeline activity type with `defineTimelineActivityType` from `twenty-sdk/define`:```ts filename="src/timeline-activity-types/post-card-created.ts"import { defineTimelineActivityType } from 'twenty-sdk/define';@@ -168,19 +163,19 @@ mutation ResetTimelineActivityType($id: UUID!) {## Configuration fields-| Field | Required | Description |-| ------------------------------------------------- | --------- | ---------------------------------------------------------------- |-| `universalIdentifier` | Yes | Stable UUID for the type across installations and upgrades |-| `name` | Yes | App-local programmatic name; must be unique within the app |-| `label` | Yes | User-facing action text used by the native renderer |-| `icon` | No | Twenty icon name displayed beside the event |-| `emit` | No | Automatic emission declaration; omit for explicit-only types |-| `emit.on` | With emit | Audit action that causes this type to be written |-| `emit.objectUniversalIdentifier` | With emit | Object whose records emit this type |-| `emit.through.relationFieldUniversalIdentifier` | No | Direct or junction relation used to fan out to related timelines |-| `emit.through.triggerFieldUniversalIdentifiers` | No | Source fields that can trigger an `updated` through event |+| Field | Required | Description |+| ------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |+| `universalIdentifier` | Yes | Stable UUID for the type across installations and upgrades |+| `name` | Yes | App-local programmatic name; must be unique within the app |+| `label` | Yes | User-facing action text used by the native renderer |+| `icon` | No | Twenty icon name displayed beside the event |+| `emit` | No | Automatic emission declaration; omit for explicit-only types |+| `emit.on` | With emit | Audit action that causes this type to be written |+| `emit.objectUniversalIdentifier` | With emit | Object whose records emit this type |+| `emit.through.relationFieldUniversalIdentifier` | No | Direct or junction relation used to fan out to related timelines |+| `emit.through.triggerFieldUniversalIdentifiers` | No | Source fields that can trigger an `updated` through event || `emit.through.happensAtFieldUniversalIdentifier` | No | Source date field used as the event's `happensAt` timestamp for `linked` events, instead of the write time |-| `frontComponentUniversalIdentifier` | No | App-owned front component mounted when the row is expanded |-| `replacesTimelineActivityTypeUniversalIdentifier` | No | Existing emit type replaced; requires `emit` |+| `frontComponentUniversalIdentifier` | No | App-owned front component mounted when the row is expanded |+| `replacesTimelineActivityTypeUniversalIdentifier` | No | Existing emit type replaced; requires `emit` |Twenty snapshots semantic identity and durable presentation fallbacks when an event is created. Historical rows keep their original action and object meaning. While the type is installed, its current translated label, icon, and front component render live; after uninstall, the snapshot fallback keeps the row readable. Resolution uses the universal identifier, so presentation also survives reinstalling the app.diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdxindex 205df2cdb48..6fd27f27c73 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx@@ -1,7 +1,7 @@---title: Conceptsdescription: How Twenty apps work — entity model, sandboxing, and the install lifecycle.-icon: "sitemap"+icon: 'sitemap'---Twenty apps are TypeScript packages that extend your workspace with custom objects, logic, UI components, and AI capabilities. They run on the Twenty platform with full sandboxing and permission controls.@@ -30,30 +30,32 @@ your-app/```<Note>- **File organization is up to you.** Entity detection is AST-based — the SDK finds `export default defineEntity(...)` calls regardless of where the file lives. The folder structure above is a convention, not a requirement.+ **File organization is up to you.** Entity detection is AST-based — the SDK+ finds `export default defineEntity(...)` calls regardless of where the file+ lives. The folder structure above is a convention, not a requirement.</Note>## Entity types-| Entity | Purpose | Docs |-|--------|---------|------|-| **Application** | App identity, default role, variables | [Application Config](/developers/extend/apps/config/application) |-| **Role** | Permission sets on objects and fields | [Roles & Permissions](/developers/extend/apps/config/roles) |-| **Object** | Custom record types with fields | [Objects](/developers/extend/apps/data/objects) |-| **Field** | Add fields to objects from other apps | [Extending Objects](/developers/extend/apps/data/extending-objects) |-| **Relation** | Bidirectional links between objects | [Relations](/developers/extend/apps/data/relations) |-| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic/logic-functions) |-| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |-| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |+| Entity | Purpose | Docs |+| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |+| **Application** | App identity, default role, variables | [Application Config](/developers/extend/apps/config/application) |+| **Role** | Permission sets on objects and fields | [Roles & Permissions](/developers/extend/apps/config/roles) |+| **Object** | Custom record types with fields | [Objects](/developers/extend/apps/data/objects) |+| **Field** | Add fields to objects from other apps | [Extending Objects](/developers/extend/apps/data/extending-objects) |+| **Relation** | Bidirectional links between objects | [Relations](/developers/extend/apps/data/relations) |+| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic/logic-functions) |+| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |+| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) || **Workflow** | Ready-made workflows with a trigger and steps | [Workflows](/developers/extend/apps/logic/workflows) |-| **Connection Provider** | OAuth credentials for third-party APIs | [Connections](/developers/extend/apps/logic/connections) |-| **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) |-| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |-| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/developers/extend/apps/layout/page-layouts) |-| **Front Component** | Sandboxed React UI inside Twenty | [Front Components](/developers/extend/apps/layout/front-components) |-| **Shared Dependencies** | Dependencies shared by the app's front components, declared in package.json | [Shared Dependencies](/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |-| **Command Menu Item** | Quick actions and Cmd+K entries | [Command Menu Items](/developers/extend/apps/layout/command-menu-items) |-| **Settings Menu Item** | Entries in the app's settings menu, each rendering a front component | [Settings Menu Items](/developers/extend/apps/layout/front-components#settings-menu-items) |+| **Connection Provider** | OAuth credentials for third-party APIs | [Connections](/developers/extend/apps/logic/connections) |+| **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) |+| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |+| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/developers/extend/apps/layout/page-layouts) |+| **Front Component** | Sandboxed React UI inside Twenty | [Front Components](/developers/extend/apps/layout/front-components) |+| **Shared Dependencies** | Dependencies shared by the app's front components, declared in package.json | [Shared Dependencies](/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |+| **Command Menu Item** | Quick actions and Cmd+K entries | [Command Menu Items](/developers/extend/apps/layout/command-menu-items) |+| **Settings Menu Item** | Entries in the app's settings menu, each rendering a front component | [Settings Menu Items](/developers/extend/apps/layout/front-components#settings-menu-items) |## Sandboxing@@ -66,10 +68,10 @@ your-app/```┌─────────────────────────────────────────────────────────┐│ Development │-│ npx create-twenty-app → yarn twenty dev (live sync) │+│ twenty app init → twenty app dev (live sync) │├─────────────────────────────────────────────────────────┤│ Build & Deploy │-│ yarn twenty dev:build → yarn twenty app:publish │+│ twenty app build → twenty app publish │├─────────────────────────────────────────────────────────┤│ Install flow ││ upload → [pre-install] → metadata migration → │@@ -80,26 +82,42 @@ your-app/└─────────────────────────────────────────────────────────┘```-- **`yarn twenty dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.-- **`yarn twenty dev:build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.+- **`twenty app dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.+- **`twenty app build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.- **Pre/post-install and uninstall hooks** — optional functions that run during installation or right before removal. See [Install Hooks](/developers/extend/apps/config/install-hooks) for details.## Next steps<CardGroup cols={2}>- <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">+ <Card+ title="Config"+ icon="screwdriver-wrench"+ href="/developers/extend/apps/config/overview"+ >Application identity, default role, and install and uninstall hooks.</Card>- <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">+ <Card+ title="Data"+ icon="database"+ href="/developers/extend/apps/data/overview"+ >Objects, fields, and bidirectional relations.</Card><Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">Logic functions, skills, agents, and OAuth connections.</Card>- <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">+ <Card+ title="Layout"+ icon="table-columns"+ href="/developers/extend/apps/layout/overview"+ >Views, navigation, page layouts, front components.</Card>- <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">+ <Card+ title="Operations"+ icon="rocket"+ href="/developers/extend/apps/operations/overview"+ >CLI, testing, remotes, CI, and publishing your app.</Card></CardGroup>diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdxindex 257950b6a53..358c85661d3 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx@@ -1,87 +1,33 @@---title: Local Server-description: Manage the local Twenty Docker server — start, stop, upgrade, parallel test instance, and manual SDK setup.-icon: "server"+description: Connect the standalone CLI to a local Twenty server.+icon: 'server'----## Managing the local server+The standalone CLI connects to a running Twenty server. It does not start or manage Docker containers.-Use `yarn twenty docker:*` to control the local Twenty container:+Use the [self-hosting guide](/developers/self-host/self-host) to run Twenty with Docker. In a Twenty repository checkout, the existing development environment also works:-| Command | What it does |-|---------|--------------|-| `yarn twenty docker:start` | Start the server (pulls the image if needed) |-| `yarn twenty docker:start 2.2.0` | Start a specific server version |-| `yarn twenty docker:start --port 3030` | Start on a custom port |-| `yarn twenty docker:stop` | Stop the server (preserves data) |-| `yarn twenty docker:status` | Show URL, version, and login credentials |-| `yarn twenty docker:logs` | Stream server logs |-| `yarn twenty docker:reset` | Wipe data and start fresh |-| `yarn twenty docker:upgrade` | Pull the latest `twenty-app-dev` image |-| `yarn twenty docker:upgrade 2.2.0` | Upgrade to a specific version |--Data persists across restarts in three Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-clickhouse` for ClickHouse logs and analytics, `twenty-app-dev-storage` for files). Use `reset` to wipe everything.--## Pinning the server version--When no version is passed, `docker:start` resolves the version from your app's `engines.twenty` range in `package.json` — the same range the server validates against when your app is installed. It starts the newest published `twenty-app-dev` image that satisfies the range, falling back to `latest` when the field is absent or no published version matches:--```json filename="package.json"-{- "engines": {- "twenty": ">=2.2.0"- }-}+```bash+bash packages/twenty-utils/setup-dev-env.sh+yarn start```-Pass a version explicitly to override the range for a single run: `yarn twenty docker:start 2.3.0`. If a container already exists on a different version, `docker:start` upgrades it in place (recreating the container while preserving your data volumes).+Then authenticate against the server URL for your workspace:-## Upgrading the server image--`yarn twenty docker:upgrade` pulls the latest image, compares digests, and only recreates the container if anything actually changed. Volumes are preserved — only the container is replaced. If a new image was pulled and the container was running, the upgrade automatically starts a new container; run `yarn twenty docker:start` afterward to wait for it to become healthy.--```bash filename="Terminal"-yarn twenty docker:upgrade # Latest-yarn twenty docker:upgrade 2.2.0 # Specific version+```bash+twenty auth login --url http://localhost:3000 --name local+twenty app apply --create --remote local```-Verify the running version with `yarn twenty docker:status` (it shows the `APP_VERSION` baked into the container).--## Running a parallel test instance+Use the actual URL and port of your server. For subdomain workspaces, use the workspace's hostname.-Pass `--test` to any `docker:*` command to manage a second, fully isolated instance — useful for integration tests or experiments without touching your main dev data:+## Integration tests-| Command | What it does |-|---------|--------------|-| `yarn twenty docker:start --test` | Start the test instance (defaults to port 2021) |-| `yarn twenty docker:stop --test` | Stop it |-| `yarn twenty docker:status --test` | Show its status |-| `yarn twenty docker:logs --test` | Stream its logs |-| `yarn twenty docker:reset --test` | Wipe its data |-| `yarn twenty docker:upgrade --test` | Upgrade its image |+Use a separate disposable server or workspace. Integration test setup installs an app and teardown uninstalls it. Set `TWENTY_API_URL` and `TWENTY_API_KEY` to that test instance before running `yarn test`.-The test instance has its own container (`twenty-app-dev-test`), volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-clickhouse`, `twenty-app-dev-test-storage`), and config — it runs alongside your main instance without conflicts. Combine `--test` with `--port` to override 2021.--## Manual setup (without the scaffolder)--Skip the scaffolder if you're adding the SDK to an existing project:--```bash filename="Terminal"-yarn add twenty-sdk twenty-client-sdk-```--Add the script to `package.json`:--```json filename="package.json"-{- "scripts": {- "twenty": "twenty"- }-}-```+The generated CI workflow provisions an isolated instance through `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` and installs the standalone CLI separately.-You can now run `yarn twenty dev`, `yarn twenty docker:start`, and the rest.+## Existing projects-<Note>-Don't install `twenty-sdk` globally — pin it per project so each app uses its own version.-</Note>+Keep `twenty-sdk` and `twenty-client-sdk` installed per project. Install the `twenty` CLI globally, then run `twenty app typecheck`, `twenty app build`, and `twenty app apply` from the app directory.diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdxindex 0d8340980b1..ea0e50796b2 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx@@ -1,10 +1,10 @@---title: Project Structuredescription: What's inside a scaffolded Twenty app — files, folders, and what each one does.-icon: "folder-tree"+icon: 'folder-tree'----A new app generated by `npx create-twenty-app` looks like this:+A new app generated by `twenty app init` looks like this:```text filename="my-twenty-app/"my-twenty-app/@@ -43,21 +43,23 @@ my-twenty-app/## Key files-| File / Folder | Purpose |-|---|---|-| `src/application-config.ts` | **Required.** The main configuration file for your app. |-| `src/default-role.ts` | Default role controlling what your logic functions can access. |-| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and metadata (display name, description). |-| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | A starter welcome page: a front component rendered by a standalone page layout, reachable from the sidebar. |-| `src/logic-functions/health-check.ts` | A starter [health check](/developers/extend/apps/logic/logic-functions#health-check) reporting `ok`. Fill it in to surface configuration problems only your app can detect. |-| `src/__tests__/` | A unit test plus an integration test (with its global setup) that syncs the app against a real server. |-| `public/` | Static assets (images, fonts) served with your app. |-| `locales/` | Translation catalogs. `en.json` is the source catalog `dev:translations-extract` fills in; the set of files here is what a sync publishes, so an empty folder declares no translations. `locales/compiled/` is written by `pull` for entries whose source strings are not in the tree yet, is published by a sync too, and is not meant to be edited by hand. |-| `AGENTS.md` / `CLAUDE.md` | Guidance for AI coding agents working on the app. |-| `CHANGELOG.md` / `SETUP.md` | Changelog of notable changes and setup instructions for local development. |+| File / Folder | Purpose |+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `src/application-config.ts` | **Required.** The main configuration file for your app. |+| `src/default-role.ts` | Default role controlling what your logic functions can access. |+| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and metadata (display name, description). |+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | A starter welcome page: a front component rendered by a standalone page layout, reachable from the sidebar. |+| `src/logic-functions/health-check.ts` | A starter [health check](/developers/extend/apps/logic/logic-functions#health-check) reporting `ok`. Fill it in to surface configuration problems only your app can detect. |+| `src/__tests__/` | A unit test plus an integration test (with its global setup) that syncs the app against a real server. |+| `public/` | Static assets (images, fonts) served with your app. |+| `locales/` | Translation catalogs. `en.json` is the source catalog `dev:translations-extract` fills in; the set of files here is what a sync publishes, so an empty folder declares no translations. `locales/compiled/` is written by `pull` for entries whose source strings are not in the tree yet, is published by a sync too, and is not meant to be edited by hand. |+| `AGENTS.md` / `CLAUDE.md` | Guidance for AI coding agents working on the app. |+| `CHANGELOG.md` / `SETUP.md` | Changelog of notable changes and setup instructions for local development. |<Note>-**File organization is up to you.** The folders above are conventions — the SDK detects entities via AST analysis on `export default defineEntity(...)` calls regardless of where the file lives.+ **File organization is up to you.** The folders above are conventions — the+ SDK detects entities via AST analysis on `export default defineEntity(...)`+ calls regardless of where the file lives.</Note>## Dependencies@@ -75,11 +77,11 @@ The Twenty SDK and UI packages belong under `devDependencies`:}```-The scaffolder pins `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` to its own version. Keep all three in sync when upgrading.+`twenty app init` pins `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` to its own version. Keep all three in sync when upgrading.-- **`twenty-sdk`** ships the `twenty` CLI and the build/scaffolding tooling. It only runs at development and build time and is never imported by your published app's runtime.+- **`twenty-sdk`** provides app definitions, runtime helpers, and renderer integration. Use the separately installed **`twenty`** package for CLI commands and build/scaffolding tooling.- **`twenty-client-sdk`** _is_ imported by your app code (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), but Twenty provides it at runtime — logic functions get it from a generated SDK layer, and front components resolve it from server-served modules. Your installed copy is only used for typechecking and the deploy-time build, so it never needs to ship in the deployed bundle.-Keeping either package under `dependencies` pulls it into the installed app's runtime bundle, where it is dead weight. `twenty dev:build` emits a warning when either is still listed under `dependencies`.+Keeping either package under `dependencies` pulls it into the installed app's runtime bundle, where it is dead weight. `twenty app build` emits a warning when either is still listed under `dependencies`.Add your app's own runtime dependencies (libraries your logic functions actually import at runtime) under `dependencies` as usual. Keep the tree lean: `dependencies` are installed into a runtime layer capped at 250MB unpacked, and a sync or install fails with a dependencies size error beyond that — UI libraries and dev tooling belong in `devDependencies`.diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdxindex f4342612423..75ba50e3334 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx@@ -1,152 +1,67 @@---title: Quick Start-icon: "rocket"-description: Create your first Twenty app in minutes.+icon: 'rocket'+description: Create your first Twenty app with the standalone CLI.----## Prerequisites+Use Node.js 24.5+ and Yarn 4. Install the CLI globally; your app keeps its own SDK dependencies.-- **Node.js 24.5+** — [Download](https://nodejs.org/)-- **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable`-- **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Twenty server. Skip if you already have Twenty running elsewhere.+## Create the project-Building a Twenty app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix.--| Phase | What you do | Tool | Result |-|---|---|---|---|-| **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk |-| **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty docker:start` | A running Twenty instance |-| **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI |-------## Phase 1 — Scaffold your project--Create a new app from the template:--```bash filename="Terminal"-npx create-twenty-app@latest my-twenty-app-```--The scaffolder is non-interactive: the directory name becomes the app name. Pass `--display-name` and `--description` to customize the generated metadata (you can also edit it later in `src/constants/universal-identifiers.ts`). This generates a TypeScript project in `my-twenty-app/` with a starter `application-config.ts`, a default role, CI/CD workflows, and an integration test.--**After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2.-------## Phase 2 — Run a local Twenty server--Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI.--The scaffolder starts one for you: with Docker running, it pulls the `twentycrm/twenty-app-dev` image, starts it on port `2020`, and authenticates the CLI against the pre-seeded demo workspace (`[email protected]`) — no sign-in required.--To connect to an existing Twenty server instead, pass `--url <your-server-url>`. Remote servers authenticate with OAuth: a browser opens so you can sign in and click **Authorize**, which gives the CLI access to your workspace. (You can also opt into OAuth locally with `--authentication-method oauth` — sign in with `[email protected]` / `[email protected]`.)--<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />-</div>--<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />-</div>--Your terminal will confirm everything is set up.--<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />-</div>--**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.--<Note>-If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty docker:start` — no need to re-scaffold.-</Note>-------## Phase 3 — Sync your changes--This is the inner loop you'll spend most of your time in.--```bash filename="Terminal"+```bash+npm install -g twenty+twenty app init my-twenty-appcd my-twenty-app-yarn twenty dev+yarn install```-This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a few seconds the server reflects the change. You'll see a live status panel in your terminal.--For more detailed output (build logs, sync requests, error traces), add `--verbose`.+`app init` writes the template only. It does not install dependencies, initialize Git, start Docker, authenticate, or sync. Customize the display name and description with `--display-name` and `--description`; use `--path` for a different destination.-<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/dev.png" alt="Dev mode terminal output" />-</div>+## Connect to Twenty-Open [http://localhost:2020/settings/developers#apps](http://localhost:2020/settings/developers#apps). You should see your app under **My apps**.+Use an existing workspace, or start a [local server](/developers/extend/apps/getting-started/local-server), then sign in:-<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />-</div>--Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.--<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />-</div>--Click **View installed app** to see the workspace install. The **About** tab shows version and management options.--<div style={{textAlign: 'center'}}>- <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app" />-</div>--**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.+```bash+twenty auth login --url https://your-workspace.twenty.com --name dev+```-### One-shot sync for CI and scripts+## Sync your changes-Use `plan` and `apply` to run the same pipeline once, without a watcher:+For the first sync, explicitly allow registration and installation:-```bash filename="Terminal"-yarn twenty plan # preview the metadata changes without applying them-yarn twenty apply # show the plan, then apply it+```bash+twenty app apply --create```-| Command | Behavior | When to use |-|---------|----------|-------------|-| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |-| `yarn twenty apply` | Single build + sync, exits `0` on success, `1` on failure. Asks for confirmation on destructive changes (pass `--force` to skip). | CI, pre-commit hooks, AI agents, scripted workflows. |-| `yarn twenty plan` | Builds and prints the metadata changes **without applying them**. | Inspecting what a sync would change before committing to it. |+Then start the development watcher:-All modes need an authenticated remote. See [Syncing & recovery](/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) for more on `plan`.+```bash+twenty app dev+```-<Note>-All three modes require your workspace to own the app's registration. The sync is refused when the `universalIdentifier` from your app config is registered to another workspace, or to no workspace yet — apps imported from the marketplace catalog start unowned and have to be claimed first. See [Registration ownership](/developers/extend/apps/operations/publishing#registration-ownership).-</Note>+Use bounded commands for scripts and agents:-<Note>-`yarn twenty dev --once` and `yarn twenty dev --once --dry-run` are deprecated aliases for `yarn twenty apply` and `yarn twenty plan`.-</Note>+```bash+twenty app plan+twenty app apply+```-### Dev mode options+`plan` previews changes. `apply` uploads and synchronizes once. Use `--no-delete` to keep remote entities missing from source, or `--yes` to permit object and field deletions without a prompt. All three commands require an authenticated remote and registration ownership.-| Flag | Description |-|------|-------------|-| `--force` | Apply destructive changes (deletes) without confirmation. |-| `--no-delete` | Keep entities that are missing from your source instead of deleting them. Also accepted by `plan` and `apply`. |-| `--debounceMs <ms>` | Set the file-change debounce delay in milliseconds (default: `1000`). |-| `--verbose` / `--debug` | Show detailed build logs, sync requests, and error traces. |+Use the standalone CLI for new apps instead of `create-twenty-app` or the SDK's bundled CLI. See the [CLI migration guide](/developers/extend/apps/operations/cli#migrating-from-the-sdk-cli).## What you can buildApps are composed of **entities** — each defined as a TypeScript file with a single `export default`:-| Entity | What it does |-|--------|-------------|-| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |-| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |-| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |-| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |-| **Views & Navigation** | Pre-configured list views and sidebar menu items |-| **Page layouts** | Custom record detail pages with tabs and widgets |+| Entity | What it does |+| ---------------------- | ----------------------------------------------------------------------------------- |+| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |+| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |+| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |+| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |+| **Views & Navigation** | Pre-configured list views and sidebar menu items |+| **Page layouts** | Custom record detail pages with tabs and widgets |Full reference: [Concepts](/developers/extend/apps/getting-started/concepts).@@ -168,19 +83,36 @@ Each skill installs with its own reference docs. The `agent-skills` branch becom## Next steps<CardGroup cols={2}>- <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">- Application identity, default role, install and uninstall hooks, public assets.+ <Card+ title="Config"+ icon="screwdriver-wrench"+ href="/developers/extend/apps/config/overview"+ >+ Application identity, default role, install and uninstall hooks, public+ assets.</Card>- <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">+ <Card+ title="Data"+ icon="database"+ href="/developers/extend/apps/data/overview"+ >Objects, fields, and bidirectional relations.</Card><Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">Logic functions, skills, agents, and OAuth connections.</Card>- <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">+ <Card+ title="Layout"+ icon="table-columns"+ href="/developers/extend/apps/layout/overview"+ >Views, navigation, page layouts, front components.</Card>- <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">+ <Card+ title="Operations"+ icon="rocket"+ href="/developers/extend/apps/operations/overview"+ >CLI, testing, remotes, CI, and publishing your app.</Card></CardGroup>diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdxindex db73c8b3145..48cd5e6afa9 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx@@ -1,65 +1,28 @@---title: Scaffolding-description: Generate entity files interactively with yarn twenty dev:add — objects, fields, views, logic functions, and more.-icon: "wand-magic-sparkles"+description: Generate app entities with twenty app add.+icon: 'wand-magic-sparkles'----Instead of creating entity files by hand, use the interactive scaffolder:+Use the standalone CLI to generate an object, field, logic function, or front component:-```bash filename="Terminal"-yarn twenty dev:add+```bash+twenty app add+twenty app add object --name invoice --name-plural invoices --no-input+twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input+twenty app add logic-function --name send-invoice --no-input+twenty app add front-component --name invoice-panel --no-input```-It prompts you to pick an entity type and walks you through the required fields, then writes a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call.+Without flags, interactive terminals prompt for missing values. For scripts and agents, supply the required fields and use `--no-input` or `--json`.-You can also pass the entity type directly to skip the first prompt:+Object generation can also create a view, navigation item, and record page layout:-```bash filename="Terminal"-yarn twenty dev:add object-yarn twenty dev:add logicFunction-yarn twenty dev:add frontComponent+```bash+twenty app add object --name invoice --name-plural invoices \+ --create-view --create-navigation-menu-item --create-page-layout --no-input```-## Available entity types+For other entity types, write the corresponding `define*` file using `twenty-sdk/define` and a valid UUID v4. Run `twenty app typecheck` and `twenty app plan` before syncing.-| Entity type | Command | Generated file |-|-------------|---------|----------------|-| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |-| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |-| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |-| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |-| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |-| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |-| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |-| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |-| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |-| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |-| Page layout widget | `yarn twenty dev:add pageLayoutWidget` | `src/page-layout-widgets/<name>.ts` |-| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |-| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |-| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |-| Timeline activity type | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/<name>.ts` |-| Settings menu item | `yarn twenty dev:add settingsMenuItem` | `src/settings-menu-items/<name>.ts` |--## What the scaffolder generates--Each entity type has its own template. For example, `yarn twenty dev:add object` asks for:--1. **Name (singular)** — e.g., `invoice`-2. **Name (plural)** — e.g., `invoices`-3. **Label (singular)** — auto-populated from the name (e.g., `Invoice`)-4. **Label (plural)** — auto-populated (e.g., `Invoices`)-5. **Also create a view, navigation menu item, and record page layout for this object?** — if you answer yes, the scaffolder also generates a table view, a sidebar entry, a record page layout and the fields view it displays, which is what makes the new object usable right away.--Other entity types have simpler prompts — most only ask for a name.--The `field` entity type is more detailed: it asks for the field name, label, type (from a list of all available field types like `TEXT`, `NUMBER`, `SELECT`, `RELATION`, etc.), and the target object's `universalIdentifier`.--## Custom output path--Use the `--path` flag to place the generated file in a custom location:--```bash filename="Terminal"-yarn twenty dev:add logicFunction --path src/custom-folder-```+`--path` selects the app directory, not a custom output folder. Run `twenty app add --help` for supported options.diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/troubleshooting.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/troubleshooting.mdxindex 45929798447..481ac17161d 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/troubleshooting.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/troubleshooting.mdx@@ -1,15 +1,15 @@---title: Troubleshootingdescription: Common first-run issues — Docker, Node version, Yarn, dependencies.-icon: "wrench"+icon: 'wrench'----- **Docker errors** — Make sure Docker Desktop (or the daemon) is running before `yarn twenty docker:start`. The error message will show the right start command for your OS.+- **Local server errors**, check your Docker or repository development environment. The standalone CLI does not manage containers.- **Wrong Node version** — Need 24.5+ (`engines.node: ^24.5.0`). Check with `node -v`.- **Yarn 4 missing** — Run `corepack enable`.- **Dependencies broken** — `rm -rf node_modules && yarn install`.- **Empty `yarn.lock`** — The build fails with "yarn.lock is empty" when the lockfile exists but has no content; run `yarn install` to regenerate it.- **`twenty-sdk` errors after upgrading to v2.8.0** — It moved from `dependencies` to `devDependencies` in v2.8.0. See [Project Structure → Dependencies](/developers/extend/apps/getting-started/project-structure#dependencies).-- **`twenty dev:build` warns about `twenty-client-sdk` under `dependencies`** — It is provided at runtime by Twenty, so it should be moved to `devDependencies` alongside `twenty-sdk`. See [Project Structure → Dependencies](/developers/extend/apps/getting-started/project-structure#dependencies).+- **`twenty app build` warns about `twenty-client-sdk` under `dependencies`** — It is provided at runtime by Twenty, so it should be moved to `devDependencies` alongside `twenty-sdk`. See [Project Structure → Dependencies](/developers/extend/apps/getting-started/project-structure#dependencies).Stuck? Ask on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).diff --git a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdxindex cc4fb2c794f..1c1484ff674 100644--- a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx@@ -65,7 +65,7 @@ export default defineCommandMenuItem({});```-After syncing with `yarn twenty dev` (or running a one-shot `yarn twenty apply`), the quick action appears in the top-right corner of the page:+After syncing with `twenty app dev` (or running a one-shot `twenty app apply`), the quick action appears in the top-right corner of the page:<div style={{ textAlign: 'center' }}><img@@ -93,12 +93,12 @@ Beyond commands, you can embed a front component directly into a record page by`widgetAvailability` decides which widget picker offers the component while a page layout is being edited. A front component is built either for record pages, where it works on the shown record, or for dashboards, so it declares one `pageLayoutType`:-| `widgetAvailability` | Offered in |-| --- | --- |-| omitted | no widget picker |-| `{ pageLayoutType: PageLayoutType.RECORD_PAGE }` | every record page |+| `widgetAvailability` | Offered in |+| ----------------------------------------------------------------------------------- | --------------------------------- |+| omitted | no widget picker |+| `{ pageLayoutType: PageLayoutType.RECORD_PAGE }` | every record page || `{ pageLayoutType: PageLayoutType.RECORD_PAGE, objectUniversalIdentifiers: [...] }` | the record pages of those objects |-| `{ pageLayoutType: PageLayoutType.DASHBOARD }` | dashboards |+| `{ pageLayoutType: PageLayoutType.DASHBOARD }` | dashboards |```tsximport {@@ -500,7 +500,7 @@ Available hooks:| `useFrontComponentId()` | `string` | This component instance's ID || `useTimelineActivityId()` | `string` or `null` | The current timeline activity ID when rendering a custom timeline row || `useColorScheme()` | `'light'` or `'dark'` | The host UI's active color scheme (`System` is already resolved) |-| `useLocation()` | `FrontComponentLocation` or `null` | The host route's pathname, query string, and hash, plus the host app's origin |+| `useLocation()` | `FrontComponentLocation` or `null` | The host route's pathname, query string, and hash, plus the host app's origin || `useToolCall()` | `FrontComponentToolCall` or `null` | The AI tool call this component is rendering, when it was surfaced from a logic function's `toolTriggerSettings` || `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |@@ -926,7 +926,7 @@ Twenty ships its component library as the [`twenty-ui`](https://www.npmjs.com/pa### Installation-New apps scaffolded with `create-twenty-app` already include `twenty-ui`. For an existing app, add it as a development dependency, pinned to the same version as `twenty-sdk` and `twenty-client-sdk`. For example, if your SDK packages use `2.51.0`:+New apps scaffolded with `twenty app init` already include `twenty-ui`. For an existing app, add it as a development dependency, pinned to the same version as `twenty-sdk` and `twenty-client-sdk`. For example, if your SDK packages use `2.51.0`:```bashyarn add -D [email protected]diff --git a/packages/twenty-docs/developers/extend/apps/layout/navigation-menu-items.mdx b/packages/twenty-docs/developers/extend/apps/layout/navigation-menu-items.mdxindex 836d5571776..b800ec86fdd 100644--- a/packages/twenty-docs/developers/extend/apps/layout/navigation-menu-items.mdx+++ b/packages/twenty-docs/developers/extend/apps/layout/navigation-menu-items.mdx@@ -1,13 +1,16 @@---title: Navigation Menu Itemsdescription: Add custom entries to the workspace sidebar — links to saved views or external URLs.-icon: "bars"+icon: 'bars'---A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/developers/extend/apps/layout/views) you ship — or to point at external URLs.```ts src/navigation-menu-items/example-navigation-menu-item.ts-import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';+import {+ defineNavigationMenuItem,+ NavigationMenuItemType,+} from 'twenty-sdk/define';import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';export default defineNavigationMenuItem({@@ -25,20 +28,23 @@ export default defineNavigationMenuItem({- `type` determines what the menu item links to. Each type pairs with a specific identifier field:- | Type | What it does | Required field |- |------|--------------|----------------|- | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |- | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |- | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |- | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |- | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |+ | Type | What it does | Required field |+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |- `position` controls ordering in the sidebar.- The enum also contains `NavigationMenuItemType.RECORD`, used internally for user-created record favorites, and `NavigationMenuItemType.AGENT_CHAT_CHANNEL`, used for chat channels pinned to favorites. Neither is usable from an app manifest (there is no field to reference a record or a channel).- `icon` and `color` are optional and customize how the entry looks.- `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.-- `yarn twenty pull` writes your navigation menu items back as `defineNavigationMenuItem()` files. An item a workspace member added to their own sidebar, and one pinned to a record, belong to that workspace rather than to your app and are reported instead; see [what pull does not write](/developers/extend/apps/operations/sync-and-recovery#pulling-an-installed-app-back-to-source).+- `twenty app pull` writes your navigation menu items back as `defineNavigationMenuItem()` files. An item a workspace member added to their own sidebar, and one pinned to a record, belong to that workspace rather than to your app and are reported instead; see [what pull does not write](/developers/extend/apps/operations/sync-and-recovery#pulling-an-installed-app-back-to-source).<Note>-**Common pitfall:** creating an object without an associated navigation menu item makes that object unreachable from the sidebar. Unless it's a technical/internal object, every custom object should have a sidebar entry pointing at it.+ **Common pitfall:** creating an object without an associated navigation menu+ item makes that object unreachable from the sidebar. Unless it's a+ technical/internal object, every custom object should have a sidebar entry+ pointing at it.</Note>diff --git a/packages/twenty-docs/developers/extend/apps/layout/page-layouts.mdx b/packages/twenty-docs/developers/extend/apps/layout/page-layouts.mdxindex b9b98659d52..1b23f70fe80 100644--- a/packages/twenty-docs/developers/extend/apps/layout/page-layouts.mdx+++ b/packages/twenty-docs/developers/extend/apps/layout/page-layouts.mdx@@ -6,10 +6,10 @@ icon: 'table-columns'A **page layout** controls how a record's detail page is arranged: which tabs appear and what widgets they contain. Use `definePageLayout()` to declare a layout for an object you own, `definePageLayoutTab()` to add a single tab to a layout that already exists (yours or a standard Twenty one), or `definePageLayoutWidget()` to add a single widget to a tab that already exists.-| Use case | Entity |-| ---------------------------------------------------------------------- | --------------------- |-| Define the entire layout for a record page on an object you own | `definePageLayout` |-| Add one tab to an existing layout (your own object, or a standard one) | `definePageLayoutTab` |+| Use case | Entity |+| --------------------------------------------------------------------------------------- | ------------------------ |+| Define the entire layout for a record page on an object you own | `definePageLayout` |+| Add one tab to an existing layout (your own object, or a standard one) | `definePageLayoutTab` || Add one widget to an existing tab (the Home tab of a record page, or a tab you defined) | `definePageLayoutWidget` |## definePageLayout@@ -63,7 +63,7 @@ export default definePageLayout({- Each `widget` inside a tab can render a [front component](/developers/extend/apps/layout/front-components), a relation list, or other built-in widget types.- A `FRONT_COMPONENT` widget can set `headerCommandMenuItemUniversalIdentifiers` to an ordered array of command menu item universal identifiers from the same app. These actions appear as icon buttons in the widget card header and keep their command-level availability and permission checks. Identifiers must be unique and must resolve when the app is installed.- `position` on tabs controls their order. Use higher values (e.g., 50) to place custom tabs after built-in ones.-- `yarn twenty pull` writes page layouts back with their tabs and widgets inline. A widget the export cannot carry yet, such as one showing your app's own front component or one of the deprecated `VIEW` type, is reported by pull instead of written; see [what pull does not write](/developers/extend/apps/operations/sync-and-recovery#pulling-an-installed-app-back-to-source).+- `twenty app pull` writes page layouts back with their tabs and widgets inline. A widget the export cannot carry yet, such as one showing your app's own front component or one of the deprecated `VIEW` type, is reported by pull instead of written; see [what pull does not write](/developers/extend/apps/operations/sync-and-recovery#pulling-an-installed-app-back-to-source).### Field widgets@@ -187,7 +187,7 @@ export default definePageLayoutTab({- `widgets` are scoped to this tab only — they reference [front components](/developers/extend/apps/layout/front-components), views, etc. exactly like widgets defined inline in `definePageLayout`.- `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.- Use this instead of `definePageLayout` when you only want to add to an existing layout. Use `definePageLayout` when you own the entire layout.-- `yarn twenty pull` writes a tab you added to a page layout you do not own back as a `definePageLayoutTab()` file, with its widgets inline, under the same limits as widgets of a `definePageLayout()`.+- `twenty app pull` writes a tab you added to a page layout you do not own back as a `definePageLayoutTab()` file, with its widgets inline, under the same limits as widgets of a `definePageLayout()`.## definePageLayoutWidget@@ -234,11 +234,14 @@ export default definePageLayoutWidget({const EXAMPLE_HOME_TAB_UNIVERSAL_IDENTIFIER =getSystemPageLayoutTabUniversalIdentifier({- objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,- pageLayoutUniversalIdentifier: getSystemRecordPageLayoutUniversalIdentifier({- objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,- objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,- }),+ objectMetadataApplicationUniversalIdentifier:+ APPLICATION_UNIVERSAL_IDENTIFIER,+ pageLayoutUniversalIdentifier:+ getSystemRecordPageLayoutUniversalIdentifier({+ objectMetadataApplicationUniversalIdentifier:+ APPLICATION_UNIVERSAL_IDENTIFIER,+ objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,+ }),title: 'Home',});```@@ -247,4 +250,4 @@ export default definePageLayoutWidget({- For a vertical list, set `position.heightBehavior` to `PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT` to fill one tab viewport, or `PageLayoutWidgetVerticalListHeightBehavior.FIT_CONTENT` to use the widget's content or configured height. Import this enum from `twenty-sdk/define`, as in the example above. If omitted, the widget keeps its built-in default. Only one active widget per tab can fill the viewport, and its index must place it after all fit-content widgets. `heightBehavior` is not supported in `GRID` or `CANVAS` positions.- `configuration` works exactly like a widget defined inline in `definePageLayout` or `definePageLayoutTab`: it references [front components](/developers/extend/apps/layout/front-components), views, fields and so on.- Use this instead of `definePageLayoutTab` when the tab already exists and you only want to place one widget on it. Use `definePageLayoutTab` when you want a tab of your own.-- `yarn twenty pull` writes a widget you added to a tab you do not own back as a `definePageLayoutWidget()` file, under the same limits as widgets of a `definePageLayout()`.+- `twenty app pull` writes a widget you added to a tab you do not own back as a `definePageLayoutWidget()` file, under the same limits as widgets of a `definePageLayout()`.diff --git a/packages/twenty-docs/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/developers/extend/apps/layout/views.mdxindex 7351d585f6c..6aaa92a3495 100644--- a/packages/twenty-docs/developers/extend/apps/layout/views.mdx+++ b/packages/twenty-docs/developers/extend/apps/layout/views.mdx@@ -41,17 +41,17 @@ export default defineView({## Optional properties-| Property | Values | Description |-|----------|--------|-------------|-| `type` | `ViewType.TABLE` (default), `ViewType.LIST`, `ViewType.KANBAN`, `ViewType.CALENDAR` | How records are laid out. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET`, `LIST_WIDGET`, and `CALENDAR_WIDGET` also exist but are used internally by page-layout widgets.) |-| `visibility` | `ViewVisibility.WORKSPACE` (default), `ViewVisibility.UNLISTED` | Whether the view is listed for the whole workspace or hidden from pickers. |-| `openRecordIn` | deprecated | No longer read: where records open is now a property of the [object](/developers/extend/apps/data/objects) (`openRecordIn` on `defineObject()`), falling back to each member's own preference. |-| `sorts` | `{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]` | Default sort order. |-| `isCompact` | `boolean` | Compact row display. |-| `mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups` | — | Group records (e.g. kanban columns) by a field. |-| `groupLoadLimit` | `8` (default), `25`, `50`, `100` | Records loaded per group before "Load more", on grouped table and list views. Kanban boards page on their own size and ignore it. |-| `kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth` | `AggregateOperations.*` | Kanban column aggregates and sizing. |-| `calendarLayout`, `calendarFieldMetadataUniversalIdentifier`, `calendarEndFieldMetadataUniversalIdentifier` | `ViewCalendarLayout.DAY` / `WEEK` / `MONTH` | Calendar views: layout, the date field that positions records, and an optional end date field. |+| Property | Values | Description |+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `type` | `ViewType.TABLE` (default), `ViewType.LIST`, `ViewType.KANBAN`, `ViewType.CALENDAR` | How records are laid out. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET`, `LIST_WIDGET`, and `CALENDAR_WIDGET` also exist but are used internally by page-layout widgets.) |+| `visibility` | `ViewVisibility.WORKSPACE` (default), `ViewVisibility.UNLISTED` | Whether the view is listed for the whole workspace or hidden from pickers. |+| `openRecordIn` | deprecated | No longer read: where records open is now a property of the [object](/developers/extend/apps/data/objects) (`openRecordIn` on `defineObject()`), falling back to each member's own preference. |+| `sorts` | `{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]` | Default sort order. |+| `isCompact` | `boolean` | Compact row display. |+| `mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups` | — | Group records (e.g. kanban columns) by a field. |+| `groupLoadLimit` | `8` (default), `25`, `50`, `100` | Records loaded per group before "Load more", on grouped table and list views. Kanban boards page on their own size and ignore it. |+| `kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth` | `AggregateOperations.*` | Kanban column aggregates and sizing. |+| `calendarLayout`, `calendarFieldMetadataUniversalIdentifier`, `calendarEndFieldMetadataUniversalIdentifier` | `ViewCalendarLayout.DAY` / `WEEK` / `MONTH` | Calendar views: layout, the date field that positions records, and an optional end date field. |All enums above are exported from `twenty-sdk/define`.@@ -74,13 +74,13 @@ filters: [Three optional properties refine a filter:-| Property | Description |-|----------|-------------|-| `subFieldName` | Targets one part of a composite field, such as `amountMicros` on a `CURRENCY` field or `primaryLinkUrl` on a `LINKS` field. |-| `relationTargetFieldMetadataUniversalIdentifier` | On a filter over a `RELATION` field, the field of the related object the value is compared against, as the advanced filter sets it when you pick a field of the related record. Leave it out to filter on the related record itself. |-| `viewFilterGroupUniversalIdentifier` + `positionInViewFilterGroup` | Place the filter in one of the view's `filterGroups` (each with a `logicalOperator` of `AND`, `OR` or `NOT` and an optional `parentViewFilterGroupUniversalIdentifier`) and order it within that group. |+| Property | Description |+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `subFieldName` | Targets one part of a composite field, such as `amountMicros` on a `CURRENCY` field or `primaryLinkUrl` on a `LINKS` field. |+| `relationTargetFieldMetadataUniversalIdentifier` | On a filter over a `RELATION` field, the field of the related object the value is compared against, as the advanced filter sets it when you pick a field of the related record. Leave it out to filter on the related record itself. |+| `viewFilterGroupUniversalIdentifier` + `positionInViewFilterGroup` | Place the filter in one of the view's `filterGroups` (each with a `logicalOperator` of `AND`, `OR` or `NOT` and an optional `parentViewFilterGroupUniversalIdentifier`) and order it within that group. |-`yarn twenty pull` writes all three back exactly as the workspace stored them.+`twenty app pull` writes all three back exactly as the workspace stored them.### Supported operands per field typediff --git a/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdxindex e9b8ae1b818..44b8bb361cb 100644--- a/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx@@ -1,7 +1,7 @@---title: Logic Functionsdescription: Define server-side TypeScript functions with HTTP, cron, and database event triggers.-icon: "bolt"+icon: 'bolt'---Logic functions are server-side TypeScript functions that run on the Twenty platform. They can be triggered by HTTP requests, cron schedules, or database events — and can also be exposed as tools for AI agents.@@ -51,6 +51,7 @@ export default defineLogicFunction({```Available trigger types:+- **httpRoute**: Exposes your function on an HTTP path and method. In app code, prefix the route path with `/s/` when using `RestApiClient`; the deployed URL uses the injected `TWENTY_FUNCTIONS_URL` base (or `<server-url>/s` when it is not set).<Note>@@ -65,22 +66,26 @@ To invoke a route-triggered logic function from a (headless) front component, seYou can also manually execute a function using the CLI:```bash filename="Terminal"-yarn twenty dev:function:exec -n create-new-post-card -p '{"key": "value"}'+twenty app exec --name create-new-post-card --payload '{"key": "value"}'``````bash filename="Terminal"-yarn twenty dev:function:exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf+twenty app exec --universal-identifier e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf```You can watch logs with:```bash filename="Terminal"-yarn twenty dev:function:logs+twenty app logs```+</Note><Note>-On the cloud, each run consumes workspace credits: a flat charge per invocation plus a per-millisecond charge for the time the function runs, so keeping `timeoutSeconds` tight and code fast keeps costs down. See [Credits](/user-guide/billing/capabilities/credits) for the rates.+ On the cloud, each run consumes workspace credits: a flat charge per+ invocation plus a per-millisecond charge for the time the function runs, so+ keeping `timeoutSeconds` tight and code fast keeps costs down. See+ [Credits](/user-guide/billing/capabilities/credits) for the rates.</Note>#### Route trigger payload@@ -102,17 +107,16 @@ const handler = async (event: RoutePayload) => {The `RoutePayload` type has the following structure:- | Property | Type | Description | Example |- |----------|------|-------------|---------|- | `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) | see section below |- | `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas) | `/users?ids=1&ids=2&ids=3&name=Alice` -> `{ ids: '1,2,3', name: 'Alice' }`|- | `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern | `/users/:id`, `/users/123` -> `{ id: '123' }` |- | `body` | `object \| null` | Parsed request body (JSON) | `{ id: 1 }` -> `{ id: 1 }` |- | `rawBody` | `string \| undefined` | Original UTF-8 request body, before JSON parsing. Useful for verifying HMAC-style webhook signatures (e.g. GitHub's `X-Hub-Signature-256`, Stripe). `undefined` when the runtime did not preserve it. | |- | `isBase64Encoded` | `boolean` | Whether the body is base64 encoded | |- | `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) | |- | `requestContext.http.path` | `string` | Raw request path | |-+| Property | Type | Description | Example |+| ---------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |+| `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) | see section below |+| `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas) | `/users?ids=1&ids=2&ids=3&name=Alice` -> `{ ids: '1,2,3', name: 'Alice' }` |+| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern | `/users/:id`, `/users/123` -> `{ id: '123' }` |+| `body` | `object \| null` | Parsed request body (JSON) | `{ id: 1 }` -> `{ id: 1 }` |+| `rawBody` | `string \| undefined` | Original UTF-8 request body, before JSON parsing. Useful for verifying HMAC-style webhook signatures (e.g. GitHub's `X-Hub-Signature-256`, Stripe). `undefined` when the runtime did not preserve it. | |+| `isBase64Encoded` | `boolean` | Whether the body is base64 encoded | |+| `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) | |+| `requestContext.http.path` | `string` | Raw request path | |#### forwardedRequestHeaders@@ -146,7 +150,8 @@ const handler = async (event: RoutePayload) => {```<Note>-Header names are normalized to lowercase. Access them using lowercase keys (e.g., `event.headers['content-type']`).+ Header names are normalized to lowercase. Access them using lowercase keys+ (e.g., `event.headers['content-type']`).</Note>#### Custom HTTP response@@ -173,7 +178,8 @@ For security reasons, response headers are restricted to an allow-list. Any head- `retry-after`<Note>-The status code must be a valid HTTP status code (between 100 and 599). Response header names are matched case-insensitively.+ The status code must be a valid HTTP status code (between 100 and 599).+ Response header names are matched case-insensitively.</Note>#### Platform error responses@@ -191,6 +197,7 @@ The trigger has two parts:- a `Response` from `twenty-sdk/logic-function` — the platform echoes that HTTP response **synchronously** and does **not** enqueue a target (use this for challenge handshakes such as Slack `url_verification`).The resolver is the single point of authorization — the URL only carries the resolver's identifier. **This is the preferred place to verify request signatures**: the resolver runs before any side effect, has access to the original `rawBody` and forwarded headers, and can reject without ever touching the target.+2. A **target** logic function — a regular per-workspace logic function — then runs in the resolved workspace with the payload returned by the resolver (or the original request payload if the resolver didn't transform it). Its return value is **not** observed by the HTTP caller when the resolver chose the enqueue path.```ts src/logic-functions/resolve-server-route.logic-function.ts@@ -213,7 +220,9 @@ const handler = async (event: RoutePayload) => {const signature = event.headers['x-hub-signature-256'] ?? '';const expected ='sha256=' +- createHmac('sha256', secret).update(event.rawBody ?? '').digest('hex');+ createHmac('sha256', secret)+ .update(event.rawBody ?? '')+ .digest('hex');const a = Buffer.from(signature);const b = Buffer.from(expected);@@ -297,7 +306,12 @@ query {```<Note>-A URL carrying the resolver's `universalIdentifier` still resolves for now, and the response carries a `Deprecation` header. A `universalIdentifier` is unique per workspace, not globally: if another registration owned by a different workspace declares the same one, the platform answers `404` for that URL instead of choosing between them. Move the URLs registered with your providers to the `id` form.+ A URL carrying the resolver's `universalIdentifier` still resolves for now,+ and the response carries a `Deprecation` header. A `universalIdentifier` is+ unique per workspace, not globally: if another registration owned by a+ different workspace declares the same one, the platform answers `404` for that+ URL instead of choosing between them. Move the URLs registered with your+ providers to the `id` form.</Note>**Answering a verification GET.** Some providers verify an endpoint before they deliver to it, by sending a `GET` carrying a challenge to the same URL they will later `POST` events to — Meta's WhatsApp Cloud API is one. A server route answers `POST` only unless you say otherwise, so declare both methods:@@ -323,32 +337,49 @@ const handler = async (event: RoutePayload) => {`httpMethods` replaces the default rather than adding to it, so `['GET']` alone makes the route reject `POST`. Only `GET` and `POST` are supported. Leave it unset unless the provider needs the second verb: a route that declares `GET` will have its resolver executed by any unauthenticated caller, including the crawlers and link unfurlers that send `GET` unprompted. Anything the platform does not have a method for is answered `405` without the resolver ever running.<Note>-**The application must be claimed and installed on its owner workspace.** Follow [Claiming your app](/developers/extend/apps/operations/publishing#claiming-your-app) to assign an owner, then install the app in that workspace. Until both are true, the resolver has nowhere to run and the server route returns `404` (`LOGIC_FUNCTION_NOT_FOUND`), even if the app is installed elsewhere. Marketplace search hides apps with server routes until this setup and all required server variables are complete. See [owner workspace costs and availability](/developers/extend/apps/operations/publishing#owner-workspace-costs-and-availability) for billing and operational details.+ **The application must be claimed and installed on its owner workspace.**+ Follow [Claiming your+ app](/developers/extend/apps/operations/publishing#claiming-your-app) to+ assign an owner, then install the app in that workspace. Until both are true,+ the resolver has nowhere to run and the server route returns `404`+ (`LOGIC_FUNCTION_NOT_FOUND`), even if the app is installed elsewhere.+ Marketplace search hides apps with server routes until this setup and all+ required server variables are complete. See [owner workspace costs and+ availability](/developers/extend/apps/operations/publishing#owner-workspace-costs-and-availability)+ for billing and operational details.</Note>**Resolver contract.** The SDK's `LogicFunctionConfig` type enforces this at compile time: as soon as you set `serverRouteTriggerSettings`, your handler is constrained to return either a `Response`, or `{ workspaceId: string; targetLogicFunctionUniversalIdentifier: string; payload?: object }` (or a `Promise` of either). On the dispatch path, the `workspaceId` must be a workspace where the target function is installed, otherwise the request is rejected with `404`. A result that matches neither shape — including one whose identifiers are not UUIDs — is rejected with `502`.-| Field | Type | Notes |-|-------|------|-------|-| `workspaceId` | `string` | Workspace UUID where the target will run. |-| `targetLogicFunctionUniversalIdentifier` | `string` | `universalIdentifier` of the logic function to invoke in that workspace. |-| `payload` | `object` (optional) | If set, replaces the request body sent to the target. |+| Field | Type | Notes |+| ---------------------------------------- | ------------------- | ------------------------------------------------------------------------ |+| `workspaceId` | `string` | Workspace UUID where the target will run. |+| `targetLogicFunctionUniversalIdentifier` | `string` | `universalIdentifier` of the logic function to invoke in that workspace. |+| `payload` | `object` (optional) | If set, replaces the request body sent to the target. |<Warning>-**Signature verification is your responsibility — verify in the resolver.** The platform does not verify request signatures. The resolver is the recommended place to do it: it runs first, with access to `event.rawBody` and the headers you listed in `forwardedRequestHeaders`, and a thrown error (or any non-matching `workspaceId`) stops the dispatch before the target is invoked. If you instead push verification down into the target, the target must be careful not to lose `rawBody` and headers — i.e. the resolver must not return a `payload`. Always verify **before** any side effect and use a constant-time comparison.+ **Signature verification is your responsibility — verify in the resolver.**+ The platform does not verify request signatures. The resolver is the+ recommended place to do it: it runs first, with access to `event.rawBody` and+ the headers you listed in `forwardedRequestHeaders`, and a thrown error (or+ any non-matching `workspaceId`) stops the dispatch before the target is+ invoked. If you instead push verification down into the target, the target+ must be careful not to lose `rawBody` and headers — i.e. the resolver must not+ return a `payload`. Always verify **before** any side effect and use a+ constant-time comparison.</Warning>**Bearer tokens.** Some providers, such as Microsoft Bot Framework, sign each request with a JWT in the `Authorization` header instead of a signature header. A server route can list `authorization` in `forwardedRequestHeaders` to receive it, and the resolver verifies it like any other signature. The platform removes the header if it carries a token issued by Twenty, so a server route never receives a Twenty session. `cookie` and `proxy-authorization` are never forwarded, and HTTP routes cannot forward any of these three headers.For request signatures, most providers sign with HMAC-SHA256; the parts that differ are the header name, the digest encoding, and the signed-payload string. A few examples:-| Provider | Headers to forward | Signed string | Digest |-|----------|--------------------|---------------|--------|+| Provider | Headers to forward | Signed string | Digest |+| ---------------------------- | ------------------------------------------------------ | ---------------------------- | -------------------------------------------------- || Svix (Recall, Resend, Clerk) | `webhook-id`, `webhook-timestamp`, `webhook-signature` | `{id}.{timestamp}.{rawBody}` | base64 (secret is base64 after stripping `whsec_`) |-| Stripe | `stripe-signature` | `{timestamp}.{rawBody}` | hex |-| GitHub | `x-hub-signature-256` | `{rawBody}` | hex (prefixed `sha256=`) |-| Shopify | `x-shopify-hmac-sha256` | `{rawBody}` | base64 |-| Slack | `x-slack-signature`, `x-slack-request-timestamp` | `v0:{timestamp}:{rawBody}` | hex (prefixed `v0=`) |+| Stripe | `stripe-signature` | `{timestamp}.{rawBody}` | hex |+| GitHub | `x-hub-signature-256` | `{rawBody}` | hex (prefixed `sha256=`) |+| Shopify | `x-shopify-hmac-sha256` | `{rawBody}` | base64 |+| Slack | `x-slack-signature`, `x-slack-request-timestamp` | `v0:{timestamp}:{rawBody}` | hex (prefixed `v0=`) |The resolver example above already shows the GitHub HMAC-SHA256 flow — adapt the header name, digest encoding, and signed-payload string per the provider you're integrating.@@ -358,6 +389,7 @@ When the resolver returns a dispatch object, the route responds `202 { queued: tThe resolver runs in the owner workspace and spends its credits, so the route answers `402` when that workspace has exhausted its allowance or has no active subscription, and `429` when a usage limit is hit. Senders that retry on `5xx` will not retry these, which is what you want: the refusal will not clear on the next attempt.When the caller must read the response body on the same request (challenge handshakes, interactive acknowledgements), return a `Response` from the **resolver** instead. The platform echoes it synchronously and skips the queue; its headers go through the same allow-list as HTTP route responses. Keep the resolver fast — some providers (e.g. Slack) time out in a few seconds. Because the resolver is reachable as a public endpoint, protect it with rate limiting at your edge.+</Note>#### Database event trigger payload@@ -381,43 +413,42 @@ type Person = {The payload includes:-| Property | Description |-|----------|-------------|-| `name` | Event name, such as `person.updated`. |-| `workspaceId` | Workspace where the event happened. |-| `objectMetadata` | Metadata for the object that changed. |-| `recordId` | Id of the changed record. |-| `userId`, `userWorkspaceId`, `workspaceMemberId` | Actor fields when the event was caused by a workspace user. |-| `properties` | Record data for the event, with `before`, `after`, `diff`, and `updatedFields` depending on the operation. |--| Event | Record data |-|-------|-------------|-| `person.created` | `event.properties.after` |-| `person.updated` | `event.properties.before`, `event.properties.after`, `event.properties.diff`, `event.properties.updatedFields` |-| `person.destroyed` | `event.properties.before` |+| Property | Description |+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |+| `name` | Event name, such as `person.updated`. |+| `workspaceId` | Workspace where the event happened. |+| `objectMetadata` | Metadata for the object that changed. |+| `recordId` | Id of the changed record. |+| `userId`, `userWorkspaceId`, `workspaceMemberId` | Actor fields when the event was caused by a workspace user. |+| `properties` | Record data for the event, with `before`, `after`, `diff`, and `updatedFields` depending on the operation. |++| Event | Record data |+| ------------------ | -------------------------------------------------------------------------------------------------------------- |+| `person.created` | `event.properties.after` |+| `person.updated` | `event.properties.before`, `event.properties.after`, `event.properties.diff`, `event.properties.updatedFields` |+| `person.destroyed` | `event.properties.before` |For soft deletes, `.deleted` follows the update-style shape because the record's `deletedAt` field changes.For permanent deletes, use `.destroyed`.<Note>-`databaseEventTriggerSettings.updatedFields` filters which update events trigger the function.-`event.properties.updatedFields` tells you which fields actually changed on the current event.+ `databaseEventTriggerSettings.updatedFields` filters which update events+ trigger the function. `event.properties.updatedFields` tells you which fields+ actually changed on the current event.</Note>`databaseEventTriggerSettings` accepts:-| Property | Description |-|----------|-------------|-| `eventName` | Event to listen on, such as `person.updated`. Supports `*` for the object name, the operation, or both. |-| `updatedFields` | Optional list of field names. On `.updated` events, only changes touching one of them trigger the function. |-| `batchMode` | Optional boolean. When `true`, the handler is called once per batch of records instead of once per record. The server decides how many records a batch holds, up to 200. |+| Property | Description |+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `eventName` | Event to listen on, such as `person.updated`. Supports `*` for the object name, the operation, or both. |+| `updatedFields` | Optional list of field names. On `.updated` events, only changes touching one of them trigger the function. |+| `batchMode` | Optional boolean. When `true`, the handler is called once per batch of records instead of once per record. The server decides how many records a batch holds, up to 200. |Created event example:```ts-type PersonCreatedEvent = DatabaseEventPayload<- ObjectRecordCreateEvent<Person>->;+type PersonCreatedEvent = DatabaseEventPayload<ObjectRecordCreateEvent<Person>>;const handler = async (event: PersonCreatedEvent) => {const person = event.properties.after;@@ -432,9 +463,7 @@ const handler = async (event: PersonCreatedEvent) => {Updated event example:```ts-type PersonUpdatedEvent = DatabaseEventPayload<- ObjectRecordUpdateEvent<Person>->;+type PersonUpdatedEvent = DatabaseEventPayload<ObjectRecordUpdateEvent<Person>>;const handler = async (event: PersonUpdatedEvent) => {const { before, after, diff, updatedFields } = event.properties;@@ -509,7 +538,10 @@ const handler = async (batch: PeopleUpdatedBatch) => {```<Note>-Batch size is not something a handler can rely on. The server decides how many events a call carries, capped at 200, and a batch holds anything from a single event up to that ceiling depending on how many the originating write produced. Write the handler to loop over `events` whatever its length.+ Batch size is not something a handler can rely on. The server decides how many+ events a call carries, capped at 200, and a batch holds anything from a single+ event up to that ceiling depending on how many the originating write produced.+ Write the handler to loop over `events` whatever its length.</Note>Events are grouped by the user who caused them before being batched, so every call covers a single actor and `context.workspaceMemberId` stays meaningful. `updatedFields` filtering is applied before batching, so a batch only contains records you asked for.@@ -535,18 +567,19 @@ const handler = async (};```-| Field | Type | Description |-|-------|------|-------------|-| `workspaceId` | `string` | The workspace the run belongs to. |-| `userWorkspaceId` | `string \| null` | The person who triggered the run, as their membership of this workspace. |-| `workspaceMemberId` | `string \| null` | The same person as a workspace member record, which is what you link records to. |-| `retryCount` | `number` | `0` on the first attempt. See [Background jobs](/developers/extend/apps/logic/background-jobs). |-| `maxRetries` | `number` | Upper bound on application-requested retries. |+| Field | Type | Description |+| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | The workspace the run belongs to. |+| `userWorkspaceId` | `string \| null` | The person who triggered the run, as their membership of this workspace. |+| `workspaceMemberId` | `string \| null` | The same person as a workspace member record, which is what you link records to. |+| `retryCount` | `number` | `0` on the first attempt. See [Background jobs](/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Upper bound on application-requested retries. |`userWorkspaceId` and `workspaceMemberId` are `null` when nobody triggered the run: cron schedules, install hooks and unauthenticated webhooks have no person behind them. They are also `null` when the person has no workspace member record, or theirs has been deleted.<Note>-**The context tells you who triggered the run.** What the run may *do* is a separate declaration, below.+ **The context tells you who triggered the run.** What the run may *do* is a+ separate declaration, below.</Note>#### Whose access a call uses@@ -555,7 +588,7 @@ Every client — `CoreApiClient`, `MetadataApiClient` and `RestApiClient` — acWhen nobody triggered the run there is no person to act as, so the same client falls back to your application's own access: cron schedules, install hooks and unauthenticated webhooks need no special handling.-Some calls legitimately need the application's own access even when a person *is* behind the run — reading your app's configuration records, or doing work that person could not do themselves. Build a second client for those:+Some calls legitimately need the application's own access even when a person _is_ behind the run — reading your app's configuration records, or doing work that person could not do themselves. Build a second client for those:```tsimport { CoreApiClient } from 'twenty-client-sdk/core';@@ -584,6 +617,7 @@ const asApplication = new RestApiClient({ runAs: 'application' });**A run nobody triggered acts as your application.** Cron schedules, install hooks and unauthenticated webhooks have no person behind them, so the default client falls back to your application's own access and keeps working. `runAs: 'application'` is only needed when you want that access in a run a person *did* trigger.Check `context.workspaceMemberId` when a function behaves differently depending on whether someone is behind it, for instance to attribute a record.+</Note>The SDK helpers that reach your application's own resources always use its access and ignore `runAs`: the [key-value store](/developers/extend/apps/logic/key-value-store), [connections](/developers/extend/apps/logic/connections), [messaging channels](/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` and [credit charging](/developers/extend/apps/logic/credits). `sendInboxMessage` also uses your application's access and ignores `runAs`, though it writes to the chats of the members you name.@@ -598,7 +632,14 @@ Logic functions can be exposed on two surfaces, each with its own trigger:A function can opt into one, the other, or both. They sit alongside `cronTriggerSettings`, `databaseEventTriggerSettings`, and `httpRouteTriggerSettings` — same pattern, same shape.<Note>-**Relationship to the workflow Code action.** The built-in **Code** action in the workflow builder is itself a logic function — Twenty creates one per Code step and exposes its editor inline. `workflowActionTriggerSettings` is how you turn that one-off, inline code into a **reusable** action: define the function once in your app and it becomes selectable in any workflow, instead of being copy-pasted into each Code step. See the [Code action](/user-guide/workflows/capabilities/workflow-actions#code) in the user guide for the end-user view.+ **Relationship to the workflow Code action.** The built-in **Code** action in+ the workflow builder is itself a logic function — Twenty creates one per Code+ step and exposes its editor inline. `workflowActionTriggerSettings` is how you+ turn that one-off, inline code into a **reusable** action: define the function+ once in your app and it becomes selectable in any workflow, instead of being+ copy-pasted into each Code step. See the [Code+ action](/user-guide/workflows/capabilities/workflow-actions#code) in the user+ guide for the end-user view.</Note>```ts src/logic-functions/enrich-company.logic-function.ts@@ -737,25 +778,31 @@ The component mounts as soon as the agent has finished streaming its arguments,Both `input` and `output` are typed `Record<string, unknown>`, so narrow each field before you use it rather than casting. That matters most for anything you hand to the DOM: a value you drop into an `href` without checking it is a string is a link the tool's output controls.<Note>-If the identifier matches no front component in the app, the chat falls back to the default step row. Front components in the AI chat run under the same [role your app declares](/developers/extend/apps/config/roles), so a widget can only read and write what the app itself is allowed to.+ If the identifier matches no front component in the app, the chat falls back+ to the default step row. Front components in the AI chat run under the same+ [role your app declares](/developers/extend/apps/config/roles), so a widget+ can only read and write what the app itself is allowed to.</Note>##### A complete workflow action example`workflowActionTriggerSettings` accepts four fields:-| Field | Purpose |-|-------|---------|-| `label` | Name shown for the action in the workflow builder's step picker. Defaults to the function `name`. |-| `icon` | Icon shown next to the action (a `tabler-icons` name, e.g. `IconBuilding`). |-| `inputSchema` | Twenty's rich `InputSchema` — what the builder renders as configurable fields (with variable pickers). Optional; inferred from the handler when omitted. |+| Field | Purpose |+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `label` | Name shown for the action in the workflow builder's step picker. Defaults to the function `name`. |+| `icon` | Icon shown next to the action (a `tabler-icons` name, e.g. `IconBuilding`). |+| `inputSchema` | Twenty's rich `InputSchema` — what the builder renders as configurable fields (with variable pickers). Optional; inferred from the handler when omitted. || `outputSchema` | Declares the shape the handler returns, so **subsequent steps can map to its output fields**. Optional; without it, the output is exposed as a single opaque value. |Putting it together — a function exposed as a workflow action, with a declared output so later steps can reference `taskId`:```ts src/logic-functions/enrich-company.logic-function.tsimport { defineLogicFunction } from 'twenty-sdk/define';-import { jsonSchemaToInputSchema, type InputJsonSchema } from 'twenty-sdk/logic-function';+import {+ jsonSchemaToInputSchema,+ type InputJsonSchema,+} from 'twenty-sdk/logic-function';import { CoreApiClient } from 'twenty-client-sdk/core';const inputSchema: InputJsonSchema = {@@ -812,7 +859,9 @@ export default defineLogicFunction({Once the app is installed, **Enrich Company** appears in the workflow builder's action picker. The builder renders `companyName` and `domain` as input fields (each able to pull values from previous steps), and downstream steps can reference the step's `taskId` and `enriched` outputs.<Note>-**Write a good `description`.** AI agents rely on the function's `description` field to decide when to use the tool. Be specific about what the tool does and when it should be called.+ **Write a good `description`.** AI agents rely on the function's `description`+ field to decide when to use the tool. Be specific about what the tool does and+ when it should be called.</Note></Accordion>@@ -830,10 +879,16 @@ const handler = async (params: { parentMessageId?: string }) => {}};```+</Note><Note>-**Install hooks** — pre-install, post-install, and uninstall handlers — share this runtime but are declared with their own define functions and don't take trigger settings. See [Install Hooks](/developers/extend/apps/config/install-hooks) for `definePreInstallLogicFunction`, `definePostInstallLogicFunction`, and `defineUninstallLogicFunction`.+ **Install hooks** — pre-install, post-install, and uninstall handlers — share+ this runtime but are declared with their own define functions and don't take+ trigger settings. See [Install+ Hooks](/developers/extend/apps/config/install-hooks) for+ `definePreInstallLogicFunction`, `definePostInstallLogicFunction`, and+ `defineUninstallLogicFunction`.</Note>## Health check@@ -869,19 +924,22 @@ export default defineHealthCheck({The result is a discriminated union, not a boolean:-| Field | Required | Description |-| --- | --- | --- |-| `status` | Yes | `OK` when there is nothing to report, otherwise `SUCCESS`, `INFO`, `WARNING`, `ERROR` or `NEUTRAL` |-| `title` | For every status but `OK` | The banner's first line on the app's settings page |-| `description` | No | A second line under the title, for what to do about it |-| `action` | No | `{ label, location }` for the banner's button. `location` is where the button redirects to: a path inside Twenty such as `/settings/billing`, optionally with a hash to select a tab, or a hash alone such as `#variables` to move to a tab of your own settings page; omit it to land on the app's configuration tab |+| Field | Required | Description |+| ------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `status` | Yes | `OK` when there is nothing to report, otherwise `SUCCESS`, `INFO`, `WARNING`, `ERROR` or `NEUTRAL` |+| `title` | For every status but `OK` | The banner's first line on the app's settings page |+| `description` | No | A second line under the title, for what to do about it |+| `action` | No | `{ label, location }` for the banner's button. `location` is where the button redirects to: a path inside Twenty such as `/settings/billing`, optionally with a hash to select a tab, or a hash alone such as `#variables` to move to a tab of your own settings page; omit it to land on the app's configuration tab |`OK` shows no banner at all; every other status renders the title in a banner coloured after it, so pick the one that matches how much the person needs to act. The statuses are Twenty's own `ApplicationHealthStatus`, so the plain string and the enum member are interchangeable:```tsimport { ApplicationHealthStatus } from 'twenty-sdk/define';-return { status: ApplicationHealthStatus.WARNING, title: 'Quota almost reached' };+return {+ status: ApplicationHealthStatus.WARNING,+ title: 'Quota almost reached',+};```Twenty runs the check when the app's settings page opens and shows the result in a banner there. Nothing is stored, so what you report is always what the check just returned.@@ -935,15 +993,15 @@ The logic function's role needs write permission on the standard `timelineActiviThe `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components.-| Client | Import | Endpoint | Generated? |-|--------|--------|----------|------------|-| `CoreApiClient` | `twenty-client-sdk/core` | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads | No, ships pre-built |+| Client | Import | Endpoint | Generated? |+| ------------------- | ---------------------------- | ---------------------------------------------- | ---------------------- |+| `CoreApiClient` | `twenty-client-sdk/core` | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |+| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads | No, ships pre-built |<AccordionGroup><Accordion title="CoreApiClient" description="Query and mutate workspace data (records, objects)">-`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty dev:build`, so it is fully typed to match your objects and fields.+`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `twenty app dev` or `twenty app build`, so it is fully typed to match your objects and fields.```tsimport { CoreApiClient } from 'twenty-client-sdk/core';@@ -1003,7 +1061,10 @@ const { createContract } = await client.mutation({The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.<Note>-**CoreApiClient is generated at dev/build time.** If you use it without running `yarn twenty dev` or `yarn twenty dev:build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema and generates a typed client using `@genql/cli`.+ **CoreApiClient is generated at dev/build time.** If you use it without+ running `twenty app dev` or `twenty app build` first, it throws an error. The+ generation happens automatically — the CLI introspects your workspace's+ GraphQL schema and generates a typed client using `@genql/cli`.</Note>#### Using CoreSchema for type annotations@@ -1083,13 +1144,14 @@ console.log(uploadedFile);// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }```-| Parameter | Type | Description |-|-----------|------|-------------|-| `fileBuffer` | `Buffer` | The raw file contents |-| `filename` | `string` | The name of the file (used for storage and display) |+| Parameter | Type | Description |+| ---------------------------------- | -------- | --------------------------------------------------------------- |+| `fileBuffer` | `Buffer` | The raw file contents |+| `filename` | `string` | The name of the file (used for storage and display) || `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |Key points:+- Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.- The MIME type is detected from the file contents once uploaded, so there is nothing to declare.- The returned `url` is a signed URL you can use to access the uploaded file.@@ -1097,13 +1159,13 @@ Key points:</Accordion></AccordionGroup>-<Note>When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:- - `TWENTY_API_URL` — Base URL of the Twenty API- - `TWENTY_APP_ACCESS_TOKEN` — Short-lived key for the default access: a person's role intersected with your application's when someone is behind the run, your application's own role when nobody is. The person is whoever triggered the run in a logic function, whoever is looking at the page in a front component.- - `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Short-lived key scoped to your application's own role alone. Logic functions only, always injected there, and what `runAs: 'application'` uses.+- `TWENTY_API_URL` — Base URL of the Twenty API+- `TWENTY_APP_ACCESS_TOKEN` — Short-lived key for the default access: a person's role intersected with your application's when someone is behind the run, your application's own role when nobody is. The person is whoever triggered the run in a logic function, whoever is looking at the page in a front component.+- `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Short-lived key scoped to your application's own role alone. Logic functions only, always injected there, and what `runAs: 'application'` uses.++You do **not** need to pass these to the clients — they read from `process.env` automatically, and [Whose access a call uses](#whose-access-a-call-uses) covers picking between them. Your application's own permissions are determined by the role declared with `defineApplicationRole()` (or referenced via `defaultRoleUniversalIdentifier` in `application-config.ts`); a run acting as a person can never exceed that role, nor theirs.- You do **not** need to pass these to the clients — they read from `process.env` automatically, and [Whose access a call uses](#whose-access-a-call-uses) covers picking between them. Your application's own permissions are determined by the role declared with `defineApplicationRole()` (or referenced via `defaultRoleUniversalIdentifier` in `application-config.ts`); a run acting as a person can never exceed that role, nor theirs.</Note>diff --git a/packages/twenty-docs/developers/extend/apps/operations/cli.mdx b/packages/twenty-docs/developers/extend/apps/operations/cli.mdxindex af82e4e985a..44038942259 100644--- a/packages/twenty-docs/developers/extend/apps/operations/cli.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/cli.mdx@@ -1,7 +1,7 @@---title: CLIdescription: Sign in to a workspace, explore its data and build apps from your terminal with the twenty CLI.-icon: "terminal"+icon: 'terminal'---The `twenty` CLI connects to Twenty workspaces from your terminal. Use it to inspect metadata, read records, send API requests, and create, sync and debug apps. It needs **Node.js 24.5 or later**.@@ -22,21 +22,23 @@ twenty --version```<Warning>-Inside an app project, use `npx twenty@latest`, not `npx twenty`. Apps depend on `twenty-sdk`, which still ships an older `twenty` binary, and `npx twenty` runs that local binary instead of this CLI.+ Inside an app project, use `npx twenty@latest`, not `npx twenty`. Apps depend+ on `twenty-sdk`, which still ships an older `twenty` binary, and `npx twenty`+ runs that local binary instead of this CLI.</Warning>The examples below use `twenty`. Prefix them with `npx twenty@latest` if you did not install it globally. Run `twenty commands` for the full command list and `twenty <command> --help` for the options of one command.-| Command | What it does |-|---------|--------------|-| `auth` | Sign in, check and remove credentials |-| `remote` | List, select, rename and remove saved workspace connections |-| `metadata` | Inspect objects and fields |-| `data` | List and read records |-| `api` | Send raw REST or GraphQL requests |-| `open` | Open the workspace in your browser |-| `app` | Create, build, sync, debug and uninstall apps |-| `doctor` | Diagnose the CLI, app SDK and workspace connection |+| Command | What it does |+| ---------- | ----------------------------------------------------------- |+| `auth` | Sign in, check and remove credentials |+| `remote` | List, select, rename and remove saved workspace connections |+| `metadata` | Inspect objects and fields |+| `data` | List and read records |+| `api` | Send raw REST or GraphQL requests |+| `open` | Open the workspace in your browser |+| `app` | Create, build, sync, debug and uninstall apps |+| `doctor` | Diagnose the CLI, app SDK and workspace connection |Every command that talks to a workspace accepts `--remote <name>` to target a saved connection other than the default one, and `--json` for structured output.@@ -106,18 +108,18 @@ npx twenty@latest app devOther app commands:-| Command | What it does |-|---------|--------------|-| `app add` | Scaffold an object, field, logic function or other entity |-| `app build` / `app typecheck` | Build or typecheck the app locally |-| `app plan` | Preview the metadata changes an apply would make |-| `app apply` | Build, upload and sync the app |-| `app generate-client` | Regenerate the typed API client without syncing |-| `app pull` | Write the installed app's metadata back to local source |-| `app translations extract` | Extract translatable strings into `locales/` catalogs |-| `app publish` | Publish the app to npm or to a private Twenty registry |-| `app install` | Install an already registered app package in the workspace |-| `app uninstall` | Remove the app and everything it owns from the workspace |+| Command | What it does |+| ----------------------------- | ---------------------------------------------------------- |+| `app add` | Scaffold an object, field, logic function or other entity |+| `app build` / `app typecheck` | Build or typecheck the app locally |+| `app plan` | Preview the metadata changes an apply would make |+| `app apply` | Build, upload and sync the app |+| `app generate-client` | Regenerate the typed API client without syncing |+| `app pull` | Write the installed app's metadata back to local source |+| `app translations extract` | Extract translatable strings into `locales/` catalogs |+| `app publish` | Publish the app to npm or to a private Twenty registry |+| `app install` | Install an already registered app package in the workspace |+| `app uninstall` | Remove the app and everything it owns from the workspace |Definitions missing from your source are deleted from the workspace by default. Pass `--no-delete` to keep them. Deleting objects or fields also deletes their data, so it requires confirmation. See [Syncing & recovery](/developers/extend/apps/operations/sync-and-recovery) for details.@@ -166,6 +168,16 @@ twenty doctor --offline`doctor` checks your Node version, which `twenty` binary is on your `PATH`, your saved connections and the app SDK, then reports what to fix.+## Scripts and tests++Build output belongs to the CLI. Do not read `.twenty/output/manifest.json` or import internal build code; read `data.manifest` from `twenty app build --json`.++## Migrating from the SDK CLI++The SDK's `twenty` binary, `twenty-sdk/cli`, `twenty-sdk/build`, and `create-twenty-app` are deprecated. Use `twenty app init`, then `yarn install` and `twenty auth login`. Keep `twenty-sdk` installed for application definitions and runtime helpers.++Replace colon commands with the commands above. The standalone CLI does not provide `docker:*` or `dev:catalog-sync`; manage servers through Docker or the repository dev environment. Run `twenty doctor` to diagnose an older SDK binary shadowing the global CLI.+## Full referenceThe [command reference](https://github.com/twentyhq/twenty/blob/main/packages/twenty-cli/docs/commands.md) covers every flag, permission, output format and exit code.diff --git a/packages/twenty-docs/developers/extend/apps/operations/overview.mdx b/packages/twenty-docs/developers/extend/apps/operations/overview.mdxindex 08ac9690ce6..61d300ae028 100644--- a/packages/twenty-docs/developers/extend/apps/operations/overview.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/overview.mdx@@ -1,35 +1,56 @@---title: Overviewdescription: Build, test, and ship your app — CLI commands, integration tests, CI, translations, and publishing to a server or to npm.-icon: "rocket"+icon: 'rocket'----The **operations layer** is everything you do *to* your app rather than *with* it: invoking CLI commands, running integration tests against a real Twenty server, configuring CI, translating its strings, and shipping releases — either as a tarball deployed to a single server or as an npm package listed in the marketplace.+The **operations layer** is everything you do _to_ your app rather than _with_ it: invoking CLI commands, running integration tests against a real Twenty server, configuring CI, translating its strings, and shipping releases — either as a tarball deployed to a single server or as an npm package listed in the marketplace.```textdevelop ─▶ test ─▶ build ─▶ deploy / publish─────── ──── ───── ─────────────────- yarn yarn yarn yarn twenty app:publish --private (tarball → one server)- twenty test twenty- dev dev:build yarn twenty app:publish (npm → marketplace)+ twenty yarn twenty twenty app publish --private (tarball → one server)+ app dev test app build+ twenty app publish (npm → marketplace)```## In this section<CardGroup cols={2}>- <Card title="CLI" icon="terminal" href="/developers/extend/apps/operations/cli">- Sign in, explore data, build apps, exec, logs and uninstall with the `twenty` CLI.+ <Card+ title="CLI"+ icon="terminal"+ href="/developers/extend/apps/operations/cli"+ >+ Sign in, explore data, build apps, exec, logs and uninstall with the+ `twenty` CLI.</Card>- <Card title="Syncing & recovery" icon="compass" href="/developers/extend/apps/operations/sync-and-recovery">+ <Card+ title="Syncing & recovery"+ icon="compass"+ href="/developers/extend/apps/operations/sync-and-recovery"+ >Which command when, reading the sync diff, and a recovery ladder.</Card>- <Card title="Testing" icon="flask" href="/developers/extend/apps/operations/testing">+ <Card+ title="Testing"+ icon="flask"+ href="/developers/extend/apps/operations/testing"+ >Vitest setup, integration tests, type checking, CI workflow.</Card>- <Card title="Translations" icon="language" href="/developers/extend/apps/operations/translations">+ <Card+ title="Translations"+ icon="language"+ href="/developers/extend/apps/operations/translations"+ >Mark strings, extract catalogs, ship your app in several languages.</Card>- <Card title="Publishing" icon="upload" href="/developers/extend/apps/operations/publishing">+ <Card+ title="Publishing"+ icon="upload"+ href="/developers/extend/apps/operations/publishing"+ >Build, deploy a tarball, publish to npm, install.</Card><Card title="Monitoring" icon="chart-line" href="/developers/extend/apps/operations/monitoring">diff --git a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdxindex c1188eaa9fb..2edcf17f8c2 100644--- a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx@@ -1,6 +1,6 @@---title: Publishing-icon: "upload"+icon: 'upload'description: Distribute your Twenty app to the marketplace or deploy it internally.---@@ -19,10 +19,10 @@ Publishing an app creates an **application registration**: the app's identity onA `universalIdentifier` is unique across the whole instance and a registration belongs to at most one workspace (its owner) — or none until it is claimed — so installing an app and developing one are two different rights:-| Action | Requirement |-|--------|-------------|-| Installing an app | The app is listed on the marketplace, pre-installed by the operator, or its registration belongs to your workspace. |-| Developing an app (`yarn twenty dev`, `apply`, `plan`) | The registration belongs to your workspace. |+| Action | Requirement |+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |+| Installing an app | The app is listed on the marketplace, pre-installed by the operator, or its registration belongs to your workspace. |+| Developing an app (`twenty app dev`, `apply`, `plan`) | The registration belongs to your workspace. |Syncing code and a manifest under an identifier is a claim of authorship, so being able to install an app never grants the right to publish code under its identity. A workspace that is not the owner is refused, whether the app is listed, pre-installed, or private.@@ -36,10 +36,10 @@ Two situations lead to that refusal:Run the build command to compile your app and generate a distribution-ready `manifest.json`:```bash filename="Terminal"-yarn twenty dev:build+twenty app build```-This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to `.twenty/output/`. Add `--tarball` to also produce a `.tgz` package for manual distribution or the publish command.+This typechecks and bundles the app into a temporary CLI snapshot. Use `--json` to inspect the manifest and artifact metadata. `twenty app publish` creates the package itself; no separate tarball build is required.## Deploying to a server (tarball)@@ -52,7 +52,7 @@ Before deploying, you need a configured remote pointing to the target server. ReAdd a remote:```bash filename="Terminal"-yarn twenty remote:add --url https://your-twenty-server.com --as production+twenty auth login --url https://your-twenty-server.com --name production```### Deploying@@ -60,9 +60,9 @@ yarn twenty remote:add --url https://your-twenty-server.com --as productionBuild and upload your app to the server in one step:```bash filename="Terminal"-yarn twenty app:publish --private+twenty app publish --private# To deploy to a specific remote:-# yarn twenty app:publish --private --remote production+# twenty app publish --private --remote production```### Sharing a deployed app@@ -82,11 +82,14 @@ When updating an already deployed tarball app, the server requires the `version`To release an update:1. Bump the `version` field in your `package.json` (e.g. `1.2.3` → `1.2.4`, `1.3.0`, or `2.0.0`)-2. Run `yarn twenty app:publish --private` (or `yarn twenty app:publish --private --remote production`)+2. Run `twenty app publish --private` (or `twenty app publish --private --remote production`)3. Workspaces that have the app installed and enabled auto-upgrade for it (in the app's General tab) are upgraded automatically in the background; the others will see the upgrade available in their settings<Note>-Pre-release tags work as expected: bumping `1.0.0-rc.1` → `1.0.0-rc.2` is allowed, and a final release like `1.0.0` is correctly recognized as higher than `1.0.0-rc.5`. The version in `package.json` must itself be a valid semver string.+ Pre-release tags work as expected: bumping `1.0.0-rc.1` → `1.0.0-rc.2` is+ allowed, and a final release like `1.0.0` is correctly recognized as higher+ than `1.0.0-rc.5`. The version in `package.json` must itself be a valid semver+ string.</Note>{/* TODO: add screenshot of the Upgrade button */}@@ -108,11 +111,11 @@ If your app uses a feature introduced in a specific Twenty server version (for eThe value is a standard [semver range](https://github.com/npm/node-semver#ranges). Common patterns:-| Range | Meaning |-|-------|---------|-| `>=2.3.0` | Any server from 2.3.0 onward |+| Range | Meaning |+| ---------------- | ---------------------------------------- |+| `>=2.3.0` | Any server from 2.3.0 onward || `>=2.3.0 <3.0.0` | 2.3.0 or later, but below the next major |-| `^2.3.0` | Same as `>=2.3.0 <3.0.0` |+| `^2.3.0` | Same as `>=2.3.0 <3.0.0` |**What happens at deploy and install time:**@@ -122,12 +125,14 @@ The value is a standard [semver range](https://github.com/npm/node-semver#ranges- If the server has no `APP_VERSION` configured, the check is skipped.<Note>-The server is the authoritative check — it validates `engines.twenty` on both tarball upload and workspace install. If you deploy a tarball out-of-band or install from the marketplace, the server still enforces compatibility.+ The server is the authoritative check — it validates `engines.twenty` on both+ tarball upload and workspace install. If you deploy a tarball out-of-band or+ install from the marketplace, the server still enforces compatibility.</Note>## Automated CI/CD (scaffolded workflows)-Apps generated with `create-twenty-app` ship with three GitHub Actions workflows out of the box, under `.github/workflows/`. CI runs with no setup, CD requires a single secret, and publishing to npm requires a one-time npm trusted-publisher setup.+Apps generated with `twenty app init` ship with three GitHub Actions workflows out of the box, under `.github/workflows/`. CI runs with no setup, CD requires a single secret, and publishing to npm requires a one-time npm trusted-publisher setup.### CI — `ci.yml`@@ -136,9 +141,11 @@ Runs integration tests on every push to `main` and every pull request.**What it does:**1. Checks out your app's source.-2. Spawns an isolated Twenty test instance using the `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` composite action (the CI equivalent of `yarn twenty docker:start --test`).-3. Enables Corepack, sets up Node.js from your `.nvmrc`, and installs dependencies with `yarn install --immutable`.-4. Runs `yarn test`, passing `TWENTY_API_URL` and `TWENTY_API_KEY` from the spawned instance so your tests can talk to a real server.+2. Spawns an isolated Twenty test instance using the `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` composite action.+3. Enables Corepack and sets up Node.js from your `.nvmrc`.+4. Installs the pinned standalone CLI in the **Install Twenty CLI** step.+5. Installs dependencies with `yarn install --immutable`, then runs lint, typecheck, and unit tests.+6. Runs `yarn test`, passing `TWENTY_API_URL` and `TWENTY_API_KEY` from the spawned instance so your tests can talk to a real server.**Config knobs:**@@ -154,18 +161,21 @@ Deploys your app to a configured Twenty server on every push to `main`, and opti**What it does:**1. Checks out the PR head (for labeled PRs) or the pushed commit.-2. Runs `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — the CI equivalent of `yarn twenty app:publish --private`.+2. Runs `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — the CI equivalent of `twenty app publish --private`.3. Runs `twentyhq/twenty/.github/actions/install-twenty-app@main` so the newly deployed version is installed into the target workspace.**Required configuration:**-| Setting | Where | Purpose |-|---------|-------|---------|-| `TWENTY_DEPLOY_URL` | `env` in `cd.yml` (defaults to `http://localhost:3000`) | The Twenty server to deploy to. Change this to your real server URL before first use. |-| `TWENTY_DEPLOY_API_KEY` | GitHub repo **Settings → Secrets and variables → Actions** | API key with deploy permission on the target server. |+| Setting | Where | Purpose |+| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |+| `TWENTY_DEPLOY_URL` | `env` in `cd.yml` (defaults to `http://localhost:2020`) | The Twenty server to deploy to. Change this to your real server URL before first use. |+| `TWENTY_DEPLOY_API_KEY` | GitHub repo **Settings → Secrets and variables → Actions** | API key with deploy permission on the target server. |<Note>-The default `TWENTY_DEPLOY_URL` of `http://localhost:3000` is a placeholder — it will not reach anything from a GitHub-hosted runner. Update it to your server's public URL (or use a self-hosted runner with network access) before enabling CD.+ The default `TWENTY_DEPLOY_URL` of `http://localhost:2020` is a placeholder —+ it will not reach anything from a GitHub-hosted runner. Update it to your+ server's public URL (or use a self-hosted runner with network access) before+ enabling CD.</Note>**Triggering a preview deploy from a PR:**@@ -179,7 +189,8 @@ Publishes your app to npm with provenance when you push a version tag (e.g. `v1.**What it does:**1. Checks out your app, sets up Node.js, and updates npm (trusted publishing requires npm 11.5.1 or later).-2. Runs `yarn twenty app:publish`, which builds the app and publishes `.twenty/output` to npm. In CI it automatically adds `--provenance` and `--access public`, so no flags are needed in the workflow.+2. Installs the pinned standalone CLI in the **Install Twenty CLI** step, then installs app dependencies with `yarn install --immutable`.+3. Runs `twenty app publish`, which builds and packs an isolated app snapshot, then publishes it to npm. In CI it automatically adds `--provenance` and `--access public`, so no flags are needed in the workflow.**One-time setup:**@@ -189,15 +200,22 @@ On npmjs.com open your package > **Settings → Trusted Publisher** and registernpm only accepts provenance from **public** source repositories. If you publish from a private repo, npm rejects the OIDC provenance bundle with an `E422 ... Unsupported GitHub Actions source repository visibility: "private"` error. To publish from a private repo, opt out of provenance by setting `TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'` in the publish step's `env` (a commented-out hint is included in the scaffolded `publish.yml`):```yaml filename=".github/workflows/publish.yml"- - name: Publish to npm- env:- TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'- run: yarn twenty app:publish+- name: Publish to npm+ env:+ TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'+ run: twenty app publish```Without GitHub provenance, the package cannot be claimed through **Claim with GitHub**. Use a public repository with provenance if you need this ownership flow.+</Note>+### Pinning the CLI version++All three generated workflows pin the standalone CLI to the version of `twenty` that ran `twenty app init`. The **Install Twenty CLI** steps in `ci.yml` and `publish.yml` use `npm install -g twenty@<version>`. In `cd.yml`, both the deploy and install actions receive the same version through their `cli-version` input.++To upgrade, update the two installation commands and both `cli-version` inputs together. These pins are separate from the `TWENTY_VERSION` server version used in CI and the reusable action references below.+### Pinning the reusable actionsThe `ci.yml` and `cd.yml` workflows reference reusable actions at `@main`, so action updates in the `twentyhq/twenty` repo are picked up automatically. If you want deterministic builds, replace `@main` with a commit SHA or release tag on each `uses:` line.@@ -209,7 +227,7 @@ Publishing to npm makes your app eligible for the Twenty marketplace. After cata### Requirements- An [npm](https://www.npmjs.com) account-- The `twenty-app` keyword in your `package.json` `keywords` array (add it manually — it is not included by default in the `create-twenty-app` template)+- The `twenty-app` keyword in your `package.json` `keywords` array (add it manually — it is not included by default in the `twenty app init` template)```json filename="package.json"{@@ -229,10 +247,7 @@ export default defineApplication({displayName: 'My App',description: 'A great app',logo: 'public/logo.png',- galleryImages: [- 'public/screenshot-1.png',- 'public/screenshot-2.png',- ],+ galleryImages: ['public/screenshot-1.png', 'public/screenshot-2.png'],});```@@ -243,7 +258,9 @@ See the [defineApplication accordion](/developers/extend/apps/config/applicationThe marketplace renders `galleryImages` in a fixed `8:5` container (for example, `1600×1000 px`).<Note>-Gallery images of any aspect ratio are displayed in full and are never cropped, but anything significantly taller or narrower than `8:5` will show empty bands on the sides.+ Gallery images of any aspect ratio are displayed in full and are never+ cropped, but anything significantly taller or narrower than `8:5` will show+ empty bands on the sides.</Note>#### Image size limit@@ -253,26 +270,20 @@ The `logo` and each `galleryImages` file must not exceed **10 MB**. Larger files### Publish```bash filename="Terminal"-yarn twenty app:publish+twenty app publish```To publish under a specific dist-tag (e.g., `beta` or `next`):```bash filename="Terminal"-yarn twenty app:publish --tag beta+twenty app publish --tag beta```### How marketplace discovery worksThe Twenty server syncs its marketplace catalog from the npm registry **every hour**.-You can trigger the sync immediately instead of waiting:--```bash filename="Terminal"-yarn twenty dev:catalog-sync-# To target a specific remote:-# yarn twenty dev:catalog-sync --remote production-```+The standalone CLI has no catalog-sync command. Wait for the server catalog sync or use the server administration tools.The metadata shown in the marketplace comes from your `defineApplication()` config — see [Marketplace metadata](#marketplace-metadata) above.@@ -280,16 +291,21 @@ The metadata shown in the marketplace comes from your `defineApplication()` confIf your app does not define an `aboutDescription` in `defineApplication()`, the marketplace will automatically use your package's `README.md` from npm as the about page content. This means you can maintain a single README for both npm and the Twenty marketplace. If you want a different description in the marketplace, explicitly set `aboutDescription`.The About tab renders markdown text only. Images do not render, whether they use markdown syntax or `<img>` tags, and raw HTML such as badges or `<div align="center">` blocks shows as plain text.+</Note>### CI publishing-The scaffolded `publish.yml` workflow described above publishes to npm automatically on version tags, with provenance. Because `yarn twenty app:publish` adds `--provenance` and `--access public` for you when it runs in CI, the workflow needs no npm flags — only the one-time trusted-publisher setup.+The scaffolded `publish.yml` workflow described above publishes to npm automatically on version tags, with provenance. Because `twenty app publish` adds `--provenance` and `--access public` for you when it runs in CI, the workflow needs no npm flags — only the one-time trusted-publisher setup.-For other CI systems (GitLab CI, CircleCI, etc.), run `yarn install` then `yarn twenty app:publish`. Provenance is emitted when the environment can mint an OIDC token and skipped automatically otherwise.+For other CI systems (GitLab CI, CircleCI, etc.), run `yarn install` then `twenty app publish`. Provenance is emitted when the environment can mint an OIDC token and skipped automatically otherwise.<Note>-**npm provenance** adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. It is also what lets you claim ownership of your app in a Twenty marketplace. See the [npm provenance docs](https://docs.npmjs.com/generating-provenance-statements) for details.+ **npm provenance** adds a trust badge to your npm listing, letting users+ verify the package was built from a specific commit in a public CI pipeline.+ It is also what lets you claim ownership of your app in a Twenty marketplace.+ See the [npm provenance+ docs](https://docs.npmjs.com/generating-provenance-statements) for details.</Note>After the package has synced into the catalog, continue with [Claiming your app](#claiming-your-app). The claim flow requires provenance pointing to a **GitHub** repository.@@ -326,7 +342,11 @@ A [server route](/developers/extend/apps/logic/logic-functions#server-route-trig3. Register the server webhook URL with your provider and test an event from a second workspace where the app is installed. Check both the resolver and the target function's logs.<Warning>-An unclaimed app, or an app not installed in its owner workspace, has no server-route resolver to run. Requests return `404` (`LOGIC_FUNCTION_NOT_FOUND`), even if the app is installed in other workspaces. These apps stay out of marketplace search until claimed, installed on the owner workspace, and configured with all required server variables.+ An unclaimed app, or an app not installed in its owner workspace, has no+ server-route resolver to run. Requests return `404`+ (`LOGIC_FUNCTION_NOT_FOUND`), even if the app is installed in other+ workspaces. These apps stay out of marketplace search until claimed, installed+ on the owner workspace, and configured with all required server variables.</Warning>### Owner workspace costs and availability@@ -344,7 +364,12 @@ Moving the GitHub repository to another personal account or organization does noIf you have trouble claiming your app, contact us on [Discord](https://discord.gg/cx5n4Jzs57) or [open a GitHub issue](https://github.com/twentyhq/twenty/issues/new/choose).<Accordion title="Self-hosted GitHub claim configuration">-The server administrator configures `APP_CLAIM_GITHUB_CLIENT_ID` and `APP_CLAIM_GITHUB_CLIENT_SECRET` with a GitHub OAuth app. Set its authorization callback URL to your `SERVER_URL` followed by `/application-registration-claim/github/callback`, for example `https://twenty.example.com/application-registration-claim/github/callback`. This configuration is already managed for you on Twenty Cloud.+ The server administrator configures `APP_CLAIM_GITHUB_CLIENT_ID` and+ `APP_CLAIM_GITHUB_CLIENT_SECRET` with a GitHub OAuth app. Set its+ authorization callback URL to your `SERVER_URL` followed by+ `/application-registration-claim/github/callback`, for example+ `https://twenty.example.com/application-registration-claim/github/callback`.+ This configuration is already managed for you on Twenty Cloud.</Accordion>## Marketplace visibility and vetting@@ -366,7 +391,7 @@ Go to the **Settings > Applications** page in Twenty, where both marketplace andYou can also install apps from the command line:```bash filename="Terminal"-yarn twenty app:install+twenty app install```<Note>@@ -375,5 +400,6 @@ The server enforces semver versioning on install, mirroring the rules on deploy:- Installing the same version that is already installed in your workspace is rejected with an `APP_ALREADY_INSTALLED` error.- Installing a lower version than the one currently installed is rejected with a `CANNOT_DOWNGRADE_APPLICATION` error.-To install a newer version, deploy or publish it first, then re-run `yarn twenty app:install`.+To install a newer version, deploy or publish it first, then re-run `twenty app install`.+</Note>diff --git a/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx b/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdxindex c7ec881f508..190e82bbf8f 100644--- a/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx@@ -1,7 +1,7 @@---title: Syncing & recoverydescription: Which command to use when, how to read the sync output, and a recovery ladder for when local metadata drifts — before reaching a full reset.-icon: "compass"+icon: 'compass'---Local app development revolves around **syncing**: the CLI rebuilds your manifest and the server applies only the difference between it and the metadata already in your workspace. This page covers which command to reach for, how to read what a sync changed, and what to do — in order — when local state looks inconsistent.@@ -9,29 +9,26 @@ Local app development revolves around **syncing**: the CLI rebuilds your manifes## Which command, when<Note>-For day-to-day local iteration you almost always want `yarn twenty dev`. Deploying and publishing are for shipping releases, **not** for the local loop.+ For day-to-day local iteration you almost always want `twenty app dev`.+ Deploying and publishing are for shipping releases, **not** for the local+ loop.</Note>-| You want to… | Command | Notes |-| --- | --- | --- |-| Iterate locally with live sync | `yarn twenty dev` | Watches your files and syncs on every change. |-| Sync once and exit (CI, scripts, hooks) | `yarn twenty apply` | One build + sync, then exits. Add `--force` to skip the destructive-change confirmation. |-| Preview changes **without applying them** | `yarn twenty plan` | Computes and prints the diff; writes nothing. |-| Sync without deleting anything | `yarn twenty apply --no-delete` | Creates and updates only: entities that exist in the workspace but not in your source are left alone. Also accepted by `plan` and `dev`. |-| Regenerate local source from the workspace | `yarn twenty pull` | **Experimental.** Writes the installed app back to define files. See below. |-| Remove the app from the workspace | `yarn twenty app:uninstall` | Add `--yes` to skip the prompt. |-| Ship a tarball to a server | `yarn twenty app:publish --private` | Requires a **strictly higher** `package.json` version — see [Publishing](/developers/extend/apps/operations/publishing). |-| Publish to the marketplace (npm) | `yarn twenty app:publish` | — |-| Install / upgrade a deployed version | `yarn twenty app:install` | Installs the version currently deployed. |-| Wipe the local server and start clean | `yarn twenty docker:reset` | Deletes **all** local data — last resort. |--<Note>-`yarn twenty dev --once` and `yarn twenty dev --once --dry-run` still work as deprecated aliases for `yarn twenty apply` and `yarn twenty plan`.-</Note>+| You want to… | Command | Notes |+| ------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |+| Iterate locally with live sync | `twenty app dev` | Watches your files and syncs on every change. |+| Sync once and exit (CI, scripts, hooks) | `twenty app apply` | One build + sync, then exits. Add `--yes` to skip the destructive-change confirmation. |+| Preview changes **without applying them** | `twenty app plan` | Computes and prints the diff; writes nothing. |+| Sync without deleting anything | `twenty app apply --no-delete` | Creates and updates only: entities that exist in the workspace but not in your source are left alone. Also accepted by `plan` and `dev`. |+| Regenerate local source from the workspace | `twenty app pull` | **Experimental.** Writes the installed app back to define files. See below. |+| Remove the app from the workspace | `twenty app uninstall` | Add `--yes` to skip the prompt. |+| Ship a tarball to a server | `twenty app publish --private` | Requires a **strictly higher** `package.json` version — see [Publishing](/developers/extend/apps/operations/publishing). |+| Publish to the marketplace (npm) | `twenty app publish` | — |+| Install / upgrade a deployed version | `twenty app install` | Installs the version currently deployed. |### Local sync does not need a version bump-The strictly-increasing `version` rule (`VERSION_ALREADY_EXISTS` on deploy, `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION` on install) applies to **`app:publish` / `app:install`** — the release path. `yarn twenty dev` syncs your manifest in place and never requires a version change, so you don't need to touch `package.json` to iterate. If you find yourself bumping the version to test a local change, you're using the release path when you want the dev loop.+The strictly-increasing `version` rule (`VERSION_ALREADY_EXISTS` on deploy, `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION` on install) applies to **`app publish` / `app install`** — the release path. `twenty app dev` syncs your manifest in place and never requires a version change, so you don't need to touch `package.json` to iterate. If you find yourself bumping the version to test a local change, you're using the release path when you want the dev loop.## Reading the sync output@@ -53,7 +50,7 @@ Plan: 2 to add, 1 to change, 1 to destroy.This is your first diagnostic: it tells you exactly which objects, fields, and layouts changed, so you can confirm a sync did what you expected before checking the UI.-Destructive changes (`to destroy`) are listed with what they drop (e.g. `objectMetadata "auditNote" — drops the table and all its rows`) and require interactive confirmation, or `--force` in scripts.+Destructive changes (`to destroy`) are listed with what they drop (e.g. `objectMetadata "auditNote" — drops the table and all its rows`) and require interactive confirmation, or `--yes` in scripts.A sync deletes every entity your app owns that your source no longer declares. When a plan contains destroys it says so and points at `--no-delete`, which makes the sync additive: creates and updates are applied, nothing missing from your source is deleted, and the settings component and uninstall hook bindings of the app stay as they are when your source does not declare them. Use it when your source is intentionally partial, for example while adopting an app that was built in the UI.@@ -67,10 +64,10 @@ Use that identifier to find the entity in your manifest (and, if needed, in the## Previewing changes (plan)-`yarn twenty plan` builds your manifest, asks the server for the migration plan, and prints it — **without applying anything**. It's the safe way to answer "what would this sync change?" before committing to it.+`twenty app plan` builds your manifest, asks the server for the migration plan, and prints it — **without applying anything**. It's the safe way to answer "what would this sync change?" before committing to it.```bash filename="Terminal"-yarn twenty plan+twenty app plan``````text filename="Terminal"@@ -92,22 +89,29 @@ A plan:- Is useful before a risky change, when reviewing an AI-generated change, or in a script that should fail if an unexpected change is about to land.<Note>-A plan only previews **metadata** changes. It also works for an app that was never synced: the server evaluates the manifest against an empty application, so the plan lists everything your source would create.+ A plan only previews **metadata** changes. It also works for an app that was+ never synced: the server evaluates the manifest against an empty application,+ so the plan lists everything your source would create.</Note>## Pulling an installed app back to source<Warning>-`yarn twenty pull` is **experimental**. It covers only part of an application today, its output shape may change between releases, and it overwrites the files that define the entities it pulls. It restores published translations into `locales/`, keeping the entries whose source strings are not in your tree yet in `locales/compiled/` so that a push does not lose them. Commit your work before running it, and review the diff.+ `twenty app pull` is **experimental**. It covers only part of an application+ today, its output shape may change between releases, and it overwrites the+ files that define the entities it pulls. It restores published translations+ into `locales/`, keeping the entries whose source strings are not in your tree+ yet in `locales/compiled/` so that a push does not lose them. Commit your work+ before running it, and review the diff.</Warning>-`yarn twenty pull` is the inverse of `apply`: it reads an application out of the workspace and writes it back as define files.+`twenty app pull` is the inverse of `apply`: it reads an application out of the workspace and writes it back as define files.```bash-yarn twenty pull -u <universalIdentifier>+twenty app pull --universal-identifier <universalIdentifier>```-Pull needs an existing project — scaffold one with `npx create-twenty-app@latest` first, then pull into it. Without `-u`, pull targets the application your local `defineApplication()` file declares. If `-u` names a different application than the one your project declares, pull refuses rather than leaving two applications in one tree: pull that one into its own directory. If the project has an application file whose identifier cannot be read, usually because dependencies are not installed, pull refuses too and asks you to run `yarn install` first. Add `-v` to expand the coverage sections of the report, which then name up to 20 identifiers per metadata type instead of only the totals.+Pull needs an existing project — scaffold one with `twenty app init` first, then pull into it. Without `--universal-identifier`, pull targets the application your local `defineApplication()` file declares. If `--universal-identifier` names a different application than the one your project declares, pull refuses rather than leaving two applications in one tree: pull that one into its own directory. If the project has an application file whose identifier cannot be read, usually because dependencies are not installed, pull refuses too and asks you to run `yarn install` first. Add `--verbose` to expand the coverage sections of the report, which then name up to 20 identifiers per metadata type instead of only the totals.**What it writes:**@@ -137,7 +141,7 @@ Each entity goes to the file that already defines it, so a second pull rewrites- **Workspace runtime state** — member and API-key role assignments, webhooks, per-user navigation and navigation items pinned to a record, all excluded by design.- **Owned by another application** — reported, never pulled.-The report at the end of a pull lists all of it, grouped by kind and reason. Everything it names as not written is still in your workspace, so push a pulled tree back with `yarn twenty apply --no-delete` until the missing kinds are covered. A pruning `yarn twenty apply` would delete them, and `yarn twenty plan` lists exactly which.+The report at the end of a pull lists all of it, grouped by kind and reason. Everything it names as not written is still in your workspace, so push a pulled tree back with `twenty app apply --no-delete` until the missing kinds are covered. A pruning `twenty app apply` would delete them, and `twenty app plan` lists exactly which.**Workspace-local state.** An entity deactivated in the workspace is written as an active definition, and the overrides the workspace made on an entity, such as a renamed label, are not written. The report lists those rows under "Written without their workspace-local state". Applying the tree back to the same workspace leaves that state untouched; another workspace gets the entity active and without the overrides.@@ -147,18 +151,23 @@ The report at the end of a pull lists all of it, grouped by kind and reason. EveWhen local metadata looks wrong, escalate in this order and stop as soon as you're unblocked. Each step is more disruptive than the last.-1. **Re-sync.** Run `yarn twenty apply` again. Syncs are idempotent — re-running a clean manifest is safe and often resolves a transient hiccup.-2. **Preview the plan.** Run `yarn twenty plan` to see exactly what the next sync intends to change, without applying it.+1. **Re-sync.** Run `twenty app apply` again. Syncs are idempotent — re-running a clean manifest is safe and often resolves a transient hiccup.+2. **Preview the plan.** Run `twenty app plan` to see exactly what the next sync intends to change, without applying it.3. **Read the named error.** If a sync fails, note the metadata type and `universalIdentifier` in the message (see above) and locate that entity in your manifest. A conflict usually points to a duplicated or re-used identifier.-4. **Uninstall and reinstall.** `yarn twenty app:uninstall`, then sync again (`yarn twenty dev`). This rebuilds the app's metadata from a clean slate while keeping the rest of your workspace intact.-5. **Full reset (last resort).** `yarn twenty docker:reset`, then re-seed and re-sync.+4. **Uninstall and reinstall.** `twenty app uninstall`, then sync again (`twenty app dev`). This rebuilds the app's metadata from a clean slate while keeping the rest of your workspace intact.+5. **Full reset (last resort).** resetting your Docker or repository development database, then re-seed and re-sync.<Warning>-`yarn twenty docker:reset` deletes **all** data in your local instance — every workspace, record, and app. Only use it once the earlier steps have failed.+ resetting your Docker or repository development database deletes **all** data+ in your local instance — every workspace, record, and app. Only use it once+ the earlier steps have failed.</Warning><Note>-Hit a metadata error? Please [open an issue](https://github.com/twentyhq/twenty/issues/new/choose) and include the failing migration message (with its metadata type and `universalIdentifier`), the `Metadata changes` output from the sync, and the commands you ran.+ Hit a metadata error? Please [open an+ issue](https://github.com/twentyhq/twenty/issues/new/choose) and include the+ failing migration message (with its metadata type and `universalIdentifier`),+ the `Metadata changes` output from the sync, and the commands you ran.</Note>## Avoid concurrent syncs on one workspacediff --git a/packages/twenty-docs/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/developers/extend/apps/operations/testing.mdxindex 03bf56e336a..762206d0e87 100644--- a/packages/twenty-docs/developers/extend/apps/operations/testing.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/testing.mdx@@ -1,10 +1,10 @@---title: Testingdescription: Vitest setup, integration tests against a real Twenty server, type checking, and CI with GitHub Actions.-icon: "flask"+icon: 'flask'----The SDK provides programmatic APIs that let you build, deploy, install, and uninstall your app from test code. Combined with [Vitest](https://vitest.dev/) and the typed API clients, you can write integration tests that verify your app works end-to-end against a real Twenty server.+Use the standalone CLI with `--json` to build, publish, install, and uninstall your app from test code. Install it globally with `npm install -g twenty`. Combined with [Vitest](https://vitest.dev/) and the typed API clients, you can write integration tests that verify your app works end-to-end against a real Twenty server.## Using npm packages@@ -22,7 +22,7 @@ Then import it in your code:import { defineLogicFunction } from 'twenty-sdk/define';import axios from 'axios';-const handler = async (): Promise<any> => {+const handler = async () => {const { data } = await axios.get('https://api.example.com/data');return { data };@@ -60,7 +60,7 @@ The build step uses esbuild to produce a single self-contained file per logic fu**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed.-**Front components** run in a Web Worker. Node built-in modules are **not** available — only npm packages that work in a browser environment. Note that the sandbox implements a *partial* DOM, so a package can build cleanly and still fail at runtime; see [Current limitations](/developers/extend/apps/layout/front-components#current-limitations).+**Front components** run in a Web Worker. Node built-in modules are **not** available — only npm packages that work in a browser environment. Note that the sandbox implements a _partial_ DOM, so a package can build cleanly and still fail at runtime; see [Current limitations](/developers/extend/apps/layout/front-components#current-limitations).Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server.@@ -81,7 +81,8 @@ import tsconfigPaths from 'vite-tsconfig-paths';import { defineConfig } from 'vitest/config';const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';-const TWENTY_API_KEY = process.env.TWENTY_API_KEY ?? '<the pre-seeded local dev key>';+const TWENTY_API_KEY =+ process.env.TWENTY_API_KEY ?? '<the pre-seeded local dev key>';// Make env vars available to globalSetup (test.env only applies to workers)process.env.TWENTY_API_URL = TWENTY_API_URL;@@ -108,131 +109,48 @@ export default defineConfig({});```-Create a global setup file that verifies the server is reachable, writes a test config for the SDK (`~/.twenty/config.test.json`), and syncs the app before tests run:+The generated template includes `src/__tests__/run-twenty.ts`, a subprocess helper that invokes the global CLI and parses its JSON result. Set `TWENTY_CLI` to an absolute executable path to use a local CLI build. It inherits `TWENTY_API_URL` and `TWENTY_API_KEY`; no home-directory config file is needed.-```ts src/__tests__/global-setup.ts-import * as fs from 'fs';-import * as os from 'os';-import * as path from 'path';--import { appDevOnce, appUninstall } from 'twenty-sdk/cli';+Use this helper for setup and teardown:-const APP_PATH = process.cwd();-const CONFIG_DIR = path.join(os.homedir(), '.twenty');+```ts src/__tests__/global-setup.ts+import { runTwenty } from './run-twenty';export async function setup() {- const apiUrl = process.env.TWENTY_API_URL!;- const apiKey = process.env.TWENTY_API_KEY!;-- // Verify the server is running- const response = await fetch(`${apiUrl}/healthz`);- if (!response.ok) {- throw new Error(`Twenty server is not reachable at ${apiUrl}.`);- }-- // Write the SDK's test config (the CLI reads config.test.json when NODE_ENV=test)- fs.mkdirSync(CONFIG_DIR, { recursive: true });- fs.writeFileSync(- path.join(CONFIG_DIR, 'config.test.json'),- JSON.stringify({- remotes: { local: { apiUrl, apiKey } },- defaultRemote: 'local',- }, null, 2),- );-- // Start from a clean slate, then sync the app- await appUninstall({ appPath: APP_PATH }).catch(() => {});-- const result = await appDevOnce({ appPath: APP_PATH });- if (!result.success) {- throw new Error(`Dev sync failed: ${result.error?.message}`);- }+ const result = await runTwenty(['app', 'apply', '--create']);+ if (!result.ok) throw new Error(result.error.message);}export async function teardown() {- await appUninstall({ appPath: APP_PATH });+ const result = await runTwenty(['app', 'uninstall', '--yes']);+ if (!result.ok) throw new Error(result.error.message);}```-## Programmatic SDK APIs--The `twenty-sdk/cli` subpath exports functions you can call directly from test code:--| Function | Description |-|----------|-------------|-| `appBuild` | Build the app and optionally pack a tarball |-| `appDeploy` | Upload a tarball to the server |-| `appDevOnce` | Build and sync the app once (same as `yarn twenty apply`) |-| `appInstall` | Install the app on the active workspace |-| `appUninstall` | Uninstall the app from the active workspace |--Each function returns a result object with `success: boolean` and either `data` or `error`.+Run integration tests against a disposable workspace: setup installs the app and teardown uninstalls it. For registry-install coverage, run `app publish --private` followed by `app install` instead of `app apply --create`.## Writing an integration test-Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace:+Use `twenty-client-sdk` to inspect data and metadata after the CLI setup completes:-```ts src/__tests__/app-install.integration-test.ts-import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';-import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';+```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';-import { afterAll, beforeAll, describe, expect, it } from 'vitest';--const APP_PATH = process.cwd();--describe('App installation', () => {- beforeAll(async () => {- const buildResult = await appBuild({- appPath: APP_PATH,- tarball: true,- onProgress: (message: string) => console.log(`[build] ${message}`),- });-- if (!buildResult.success) {- throw new Error(`Build failed: ${buildResult.error?.message}`);- }-- const deployResult = await appDeploy({- tarballPath: buildResult.data.tarballPath!,- onProgress: (message: string) => console.log(`[deploy] ${message}`),- });-- if (!deployResult.success) {- throw new Error(`Deploy failed: ${deployResult.error?.message}`);- }-- const installResult = await appInstall({ appPath: APP_PATH });-- if (!installResult.success) {- throw new Error(`Install failed: ${installResult.error?.message}`);- }- });-- afterAll(async () => {- await appUninstall({ appPath: APP_PATH });- });-- it('should find the installed app in the workspace', async () => {- const metadataClient = new MetadataApiClient();-- const result = await metadataClient.query({- findManyApplications: {- id: true,- name: true,- universalIdentifier: true,- },- });-- const installedApp = result.findManyApplications.find(- (app: { universalIdentifier: string }) =>- app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,- );-- expect(installedApp).toBeDefined();+import { expect, it } from 'vitest';+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';++it('installs the app', async () => {+ const result = await new MetadataApiClient().query({+ findOneApplication: {+ __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },+ id: true,+ },});+ expect(result.findOneApplication.id).toBeTruthy();});```+Tests should use the standalone CLI instead of the SDK's programmatic CLI/build exports. For a manifest, read `data.manifest` from `twenty app build --json`. For deployed function tests, use the metadata client's `executeOneLogicFunction` mutation with a user token. Resolve the function within the installed application's ID before invoking it.+## Running testsMake sure your local Twenty server is running, then:@@ -252,7 +170,7 @@ yarn test:watchYou can also run type checking on your app without running tests:```bash filename="Terminal"-yarn twenty dev:typecheck+twenty app typecheck```This runs `tsc --noEmit` against your app's `tsconfig.json` and reports any type errors. Scaffolded apps also ship a `yarn typecheck` script that covers test files too (`tsconfig.spec.json`).diff --git a/packages/twenty-docs/developers/extend/apps/operations/translations.mdx b/packages/twenty-docs/developers/extend/apps/operations/translations.mdxindex 33a171eeee7..71c1f0ac8df 100644--- a/packages/twenty-docs/developers/extend/apps/operations/translations.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/translations.mdx@@ -1,11 +1,11 @@---title: Translationsdescription: Ship your app in multiple languages — translate manifest labels and UI strings through one locales catalog.-icon: "language"+icon: 'language'---Twenty apps are authored in **English**: the strings in your source and manifest-are the English source text, `en` is the source locale you translate *from*, and+are the English source text, `en` is the source locale you translate _from_, andany locale left untranslated falls back to it.Your app has two kinds of translatable text, and both flow through the same@@ -47,7 +47,11 @@ const Card = ({ count, name }: { count: number; name: string }) => {<p>{t('Saved {count} cards', { count })}</p>{/* Resolve a lazily-declared descriptor */}- <ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>+ <ul>+ {STATUSES.map((s) => (+ <li key={s.id}>{t(s.label)}</li>+ ))}+ </ul></section>);};@@ -73,7 +77,7 @@ differently:```tsxt({ message: 'Open', context: 'door' });t({ message: 'Open', context: 'window' });-<Trans context="card-title">Untitled</Trans>+<Trans context="card-title">Untitled</Trans>;```Contextual strings appear in locale catalogs as a group keyed by their@@ -87,8 +91,8 @@ the same word can translate differently as an object name and as a view name.Run the extract command from your app directory:```bash-twenty dev:translations-extract # collect strings into locales/en.json-twenty dev:translations-extract --locale fr-FR # also scaffold a target locale+twenty app translations extract # collect strings into locales/en.json+twenty app translations extract --locale fr-FR # also scaffold a target locale```Extraction collects both your manifest labels and the `t()`/`msg()`/`Trans`@@ -118,7 +122,7 @@ translation. Any string left empty falls back to the source text.## How it runs-`twenty dev:build` compiles the catalogs and serves the right language for the+`twenty app build` compiles the catalogs and serves the right language for thecurrent user: manifest labels are resolved server-side, and front-componentcatalogs are baked into each component bundle. At runtime a component reads thelocale from its execution context (the host's current language) and resolves@@ -126,11 +130,11 @@ each string against its catalog, falling back to the source when a translationis missing. Switching language in the host re-renders `Trans` and`useTranslate().t` strings live.-Manifest labels are compiled on every sync — `twenty dev:build`, `twenty apply`-and the continuous `twenty dev` watch alike — so editing a locale file and+Manifest labels are compiled on every sync — `twenty app build`, `twenty app apply`+and the continuous `twenty app dev` watch alike — so editing a locale file andsyncing is enough to see the new text. Front component catalogs are baked intoeach component bundle at build time, so changing one of those still means-re-running `twenty dev:build` (and redeploying).+re-running `twenty app build` (and redeploying).## Pulling translationsdiff --git a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/data-model.mdx b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/data-model.mdxindex 6a3c4cc90d9..4949add9338 100644--- a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/data-model.mdx+++ b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/data-model.mdx@@ -1,6 +1,6 @@---title: 1. Data model-icon: "database"+icon: 'database'description: Model documents and templates with objects, fields, and a relation.---@@ -11,15 +11,15 @@ Scaffold each entity file with the CLI — it generates a valid UUID and the rigfolder for you:```bash filename="Terminal"-yarn twenty dev:add object+twenty app add object```Below we show the finished files.<Note>-Every `*_UNIVERSAL_IDENTIFIER` constant lives in-`src/constants/universal-identifiers.ts` and is imported where used. The snippets-below omit those imports for brevity — keep them in your own files.+ Every `*_UNIVERSAL_IDENTIFIER` constant lives in+ `src/constants/universal-identifiers.ts` and is imported where used. The+ snippets below omit those imports for brevity — keep them in your own files.</Note>## The template object@@ -41,28 +41,54 @@ export default defineObject({labelIdentifierFieldMetadataUniversalIdentifier:TEMPLATE_NAME_FIELD_UNIVERSAL_IDENTIFIER,fields: [- { universalIdentifier: TEMPLATE_NAME_FIELD_UNIVERSAL_IDENTIFIER,- type: FieldType.TEXT, name: 'name', label: 'Name', icon: 'IconAbc' },- { universalIdentifier: TEMPLATE_BODY_FIELD_UNIVERSAL_IDENTIFIER,- type: FieldType.RICH_TEXT, name: 'body', label: 'Body', icon: 'IconFileText',- description: 'Use {{placeholders}} like {{name.firstName}} or {{jobTitle}}.' },- { universalIdentifier: TEMPLATE_TARGET_FIELD_UNIVERSAL_IDENTIFIER,- type: FieldType.SELECT, name: 'target', label: 'Target', icon: 'IconTarget',+ {+ universalIdentifier: TEMPLATE_NAME_FIELD_UNIVERSAL_IDENTIFIER,+ type: FieldType.TEXT,+ name: 'name',+ label: 'Name',+ icon: 'IconAbc',+ },+ {+ universalIdentifier: TEMPLATE_BODY_FIELD_UNIVERSAL_IDENTIFIER,+ type: FieldType.RICH_TEXT,+ name: 'body',+ label: 'Body',+ icon: 'IconFileText',+ description:+ 'Use {{placeholders}} like {{name.firstName}} or {{jobTitle}}.',+ },+ {+ universalIdentifier: TEMPLATE_TARGET_FIELD_UNIVERSAL_IDENTIFIER,+ type: FieldType.SELECT,+ name: 'target',+ label: 'Target',+ icon: 'IconTarget',defaultValue: `'PERSON'`,options: [- { id: TEMPLATE_TARGET_OPTION_PERSON_UNIVERSAL_IDENTIFIER,- value: 'PERSON', label: 'Person', color: 'blue', position: 0 },- { id: TEMPLATE_TARGET_OPTION_COMPANY_UNIVERSAL_IDENTIFIER,- value: 'COMPANY', label: 'Company', color: 'green', position: 1 },- ] },+ {+ id: TEMPLATE_TARGET_OPTION_PERSON_UNIVERSAL_IDENTIFIER,+ value: 'PERSON',+ label: 'Person',+ color: 'blue',+ position: 0,+ },+ {+ id: TEMPLATE_TARGET_OPTION_COMPANY_UNIVERSAL_IDENTIFIER,+ value: 'COMPANY',+ label: 'Company',+ color: 'green',+ position: 1,+ },+ ],+ },],});```<Warning>-`SELECT` option **values** must be `UPPER_CASE` (`PERSON`, not `person`), and the-`defaultValue` is wrapped in extra quotes: `` `'PERSON'` ``. The `label` is what-users see.+ `SELECT` option **values** must be `UPPER_CASE` (`PERSON`, not `person`), and+ the `defaultValue` is wrapped in extra quotes: `` `'PERSON'` ``. The `label`+ is what users see.</Warning>## The document object@@ -77,7 +103,12 @@ Each document should point back to the template it came from. Relations are**bidirectional** — you define both sides, each in its own field file.```ts filename="src/fields/document-template-relation.field.ts"-import { defineField, FieldType, OnDeleteAction, RelationType } from 'twenty-sdk/define';+import {+ defineField,+ FieldType,+ OnDeleteAction,+ RelationType,+} from 'twenty-sdk/define';// The "many" side: each document belongs to one template.export default defineField({@@ -104,15 +135,18 @@ See [Relations](/developers/extend/apps/data/relations) for the full pattern.## See it in Twenty-With `yarn twenty dev` running, open **Settings → Data model**. Both objects+With `twenty app dev` running, open **Settings → Data model**. Both objectsappear, tagged with your app.<Frame caption="Both custom objects, owned by the Document Generator app.">- <img src="/images/docs/developers/extends/apps/document-generator/01-data-model.png" alt="Data model settings showing Documents and Document templates" />+ <img+ src="/images/docs/developers/extends/apps/document-generator/01-data-model.png"+ alt="Data model settings showing Documents and Document templates"+ /></Frame>-Create one template to test with — name it *Sales proposal*, set **Target** to-*Person*, and paste a body with a few placeholders:+Create one template to test with — name it _Sales proposal_, set **Target** to+_Person_, and paste a body with a few placeholders:```textDear {{name.firstName}} {{name.lastName}},@@ -124,12 +158,19 @@ The Team```<Frame caption="A template record. The body keeps its placeholders until a document is generated.">- <img src="/images/docs/developers/extends/apps/document-generator/03-template-record.png" alt="A Sales proposal template record with placeholder body" />+ <img+ src="/images/docs/developers/extends/apps/document-generator/03-template-record.png"+ alt="A Sales proposal template record with placeholder body"+ /></Frame>**After this step:** you have `documentTemplate` and `document` objects, linked bya relation, and one template to generate from. Next, the logic that fills it in.-<Card title="Next: generating documents →" icon="bolt" href="/developers/extend/apps/tutorials/document-generator/generating-documents">+<Card+ title="Next: generating documents →"+ icon="bolt"+ href="/developers/extend/apps/tutorials/document-generator/generating-documents"+>Write the logic function that fills the template.</Card>diff --git a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/http-routes.mdx b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/http-routes.mdxindex 39a457585a9..92dfefe47bd 100644--- a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/http-routes.mdx+++ b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/http-routes.mdx@@ -1,6 +1,6 @@---title: 3. HTTP routes-icon: "globe"+icon: 'globe'description: Trigger the function over HTTP and render documents as web pages.---@@ -71,13 +71,19 @@ import { CoreApiClient } from 'twenty-client-sdk/core';import { documentHtmlPage } from 'src/utils/render-document';const htmlResponse = (html: string, status = 200): Response =>- new Response(html, { status, headers: { 'Content-Type': 'text/html; charset=utf-8' } });+ new Response(html, {+ status,+ headers: { 'Content-Type': 'text/html; charset=utf-8' },+ });const handler = async (event: RoutePayload): Promise<Response> => {const documentId = event.queryStringParameters?.id;if (!documentId) {- return htmlResponse(documentHtmlPage('Missing document id', 'Provide ?id=<documentId>.'), 400);+ return htmlResponse(+ documentHtmlPage('Missing document id', 'Provide ?id=<documentId>.'),+ 400,+ );}// Filtered list query so an unknown id renders a clean 404 page instead of throwing.@@ -90,10 +96,18 @@ const handler = async (event: RoutePayload): Promise<Response> => {const document = documents?.edges?.[0]?.node;if (!document?.id) {- return htmlResponse(documentHtmlPage('Document not found', `No document with id ${documentId}.`), 404);+ return htmlResponse(+ documentHtmlPage(+ 'Document not found',+ `No document with id ${documentId}.`,+ ),+ 404,+ );}- return htmlResponse(documentHtmlPage(document.name ?? 'Document', document.content ?? ''));+ return htmlResponse(+ documentHtmlPage(document.name ?? 'Document', document.content ?? ''),+ );};export default defineLogicFunction({@@ -133,18 +147,24 @@ http://localhost:2020/s/documents/view?id=<documentId>```<Frame caption="The public GET route renders the document as a printable page.">- <img src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png" alt="A rendered document web page" />+ <img+ src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png"+ alt="A rendered document web page"+ /></Frame><Tip>-You can also stream a function's logs while testing with-`yarn twenty dev:function:logs`, or invoke it directly with-`yarn twenty dev:function:exec`.+ You can also stream a function's logs while testing with `twenty app logs`, or+ invoke it directly with `twenty app exec`.</Tip>**After this step:** the app can generate documents over HTTP and serve them asweb pages. Now let's make it usable without `curl`.-<Card title="Next: building the UI →" icon="table-columns" href="/developers/extend/apps/tutorials/document-generator/building-the-ui">+<Card+ title="Next: building the UI →"+ icon="table-columns"+ href="/developers/extend/apps/tutorials/document-generator/building-the-ui"+>Views, navigation, a command, and a front component.</Card>diff --git a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/overview.mdx b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/overview.mdxindex 50388f27ea5..bf3bc1caa74 100644--- a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/overview.mdx+++ b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/overview.mdx@@ -1,6 +1,6 @@----title: "Tutorial: Document Generator"-icon: "wand-magic-sparkles"+title: 'Tutorial: Document Generator'+icon: 'wand-magic-sparkles'description: Build a real Twenty app that generates personalized documents from your CRM data.---@@ -12,45 +12,53 @@ document for any Person or Company in one click — from the command menu, fromAI agent, or from a workflow.<Frame caption="One template, generated for a specific person, opened as a printable page.">- <img src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png" alt="A generated Sales proposal document" />+ <img+ src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png"+ alt="A generated Sales proposal document"+ /></Frame>## What you'll learnEach chapter adds one capability. By the end you'll have touched most of the SDK.-| Chapter | Capability | Reference |-|---|---|---|-| [1. Data model](/developers/extend/apps/tutorials/document-generator/data-model) | Objects, fields, and a relation | [Data](/developers/extend/apps/data/overview) |-| [2. Generating documents](/developers/extend/apps/tutorials/document-generator/generating-documents) | A logic function (AI tool + workflow action) that fills a Markdown template and attaches a polished PDF | [Logic functions](/developers/extend/apps/logic/logic-functions) |-| [3. HTTP routes](/developers/extend/apps/tutorials/document-generator/http-routes) | Serving JSON and a shareable HTML page from routes | [Logic functions](/developers/extend/apps/logic/logic-functions) |-| [4. Building the UI](/developers/extend/apps/tutorials/document-generator/building-the-ui) | Views, navigation, command menu, and front components that preview a document and edit a template | [Layout](/developers/extend/apps/layout/overview) |-| [5. An AI agent](/developers/extend/apps/tutorials/document-generator/ai-agent) | Agent + skill | [Skills & agents](/developers/extend/apps/logic/skills-and-agents) |-| [6. Publishing](/developers/extend/apps/tutorials/document-generator/publishing) | Ship it to the marketplace | [Publishing](/developers/extend/apps/operations/publishing) |+| Chapter | Capability | Reference |+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |+| [1. Data model](/developers/extend/apps/tutorials/document-generator/data-model) | Objects, fields, and a relation | [Data](/developers/extend/apps/data/overview) |+| [2. Generating documents](/developers/extend/apps/tutorials/document-generator/generating-documents) | A logic function (AI tool + workflow action) that fills a Markdown template and attaches a polished PDF | [Logic functions](/developers/extend/apps/logic/logic-functions) |+| [3. HTTP routes](/developers/extend/apps/tutorials/document-generator/http-routes) | Serving JSON and a shareable HTML page from routes | [Logic functions](/developers/extend/apps/logic/logic-functions) |+| [4. Building the UI](/developers/extend/apps/tutorials/document-generator/building-the-ui) | Views, navigation, command menu, and front components that preview a document and edit a template | [Layout](/developers/extend/apps/layout/overview) |+| [5. An AI agent](/developers/extend/apps/tutorials/document-generator/ai-agent) | Agent + skill | [Skills & agents](/developers/extend/apps/logic/skills-and-agents) |+| [6. Publishing](/developers/extend/apps/tutorials/document-generator/publishing) | Ship it to the marketplace | [Publishing](/developers/extend/apps/operations/publishing) |## PrerequisitesYou should have finished the [Quick Start](/developers/extend/apps/getting-started/quick-start):-a local Twenty server running on port `2020` and the CLI authenticated to it.+a Twenty workspace (cloud or local) and the CLI authenticated to it.-If not, scaffold and start one now:+If the server or authentication is not ready, complete the [Quick Start](/developers/extend/apps/getting-started/quick-start) first. Then create and install the tutorial app:```bash filename="Terminal"-npx create-twenty-app@latest document-generator+twenty app init document-generatorcd document-generator-yarn twenty dev+yarn install+twenty app apply --create+twenty app dev```<Note>-Prefer to read the finished code? The complete app lives in-[`packages/twenty-apps/examples/document-generator`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/document-generator).-Every snippet below is copied from it.+ Prefer to read the finished code? The complete app lives in+ [`packages/twenty-apps/examples/document-generator`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/document-generator).+ Every snippet below is copied from it.</Note>## How the app fits together<Frame>- <img src="/images/docs/developers/extends/apps/document-generator/how-it-fits.svg" alt="A template with placeholders is generated into a polished document with a PDF, triggered from the command menu, an AI agent, a workflow, or a shareable link" />+ <img+ src="/images/docs/developers/extends/apps/document-generator/how-it-fits.svg"+ alt="A template with placeholders is generated into a polished document with a PDF, triggered from the command menu, an AI agent, a workflow, or a shareable link"+ /></Frame>You write a **template** once in a rich-text editor, with `{{placeholders}}`. Picking a@@ -61,10 +69,14 @@ one generator.## Keep this loop running-Leave `yarn twenty dev` running in a terminal for the whole tutorial. Every time+Leave `twenty app dev` running in a terminal for the whole tutorial. Every timeyou add or edit a file under `src/`, it re-syncs to your server within a fewseconds, so you can watch each capability appear in the UI as you build it.-<Card title="Start building →" icon="database" href="/developers/extend/apps/tutorials/document-generator/data-model">+<Card+ title="Start building →"+ icon="database"+ href="/developers/extend/apps/tutorials/document-generator/data-model"+>Chapter 1: model documents and templates.</Card>diff --git a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/publishing.mdx b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/publishing.mdxindex cc3e181fb44..a097fbb625d 100644--- a/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/publishing.mdx+++ b/packages/twenty-docs/developers/extend/apps/tutorials/document-generator/publishing.mdx@@ -1,6 +1,6 @@---title: 6. Publishing-icon: "rocket"+icon: 'rocket'description: Add marketplace metadata and publish your app.---@@ -31,8 +31,8 @@ export default defineApplication({```<Tip>-The default role is declared with `defineApplicationRole()` in its own file — you-don't pass `defaultRoleUniversalIdentifier` here anymore.+ The default role is declared with `defineApplicationRole()` in its own file —+ you don't pass `defaultRoleUniversalIdentifier` here anymore.</Tip>Also add the `twenty-app` keyword to `package.json` so the app is discoverable:@@ -60,9 +60,9 @@ export default defineApplication({```<Tip>-Lead with the payoff: make the first screenshot the finished result (a generated-document), then show how it's triggered and authored. Use crisp, high-resolution-captures — they're the first thing a user sees.+ Lead with the payoff: make the first screenshot the finished result (a+ generated document), then show how it's triggered and authored. Use crisp,+ high-resolution captures — they're the first thing a user sees.</Tip>Give `README.md` the same treatment — it's the front page on npm and GitHub.@@ -77,7 +77,7 @@ Run the same gates CI does:yarn lint # oxlintyarn typecheck # tsgoyarn test:unit # unit tests-yarn twenty plan # preview the metadata diff+twenty app plan # preview the metadata diff```The plan prints exactly what would change on the server without applying it —@@ -89,18 +89,18 @@ a good final sanity check. See```bash filename="Terminal"# Public app → npm (default)-yarn twenty app:publish+twenty app publish# Or deploy privately to a specific server's registry-yarn twenty app:publish --private -r <remote>+twenty app publish --private -r <remote>```-`app:publish` builds and publishes to npm by default; `--private` uploads a+`twenty app publish` builds and publishes to npm by default; `--private` uploads atarball to a Twenty server's private registry instead. To surface a published appin an instance's marketplace, trigger a catalog sync:```bash filename="Terminal"-yarn twenty dev:catalog-sync -r <remote>+# Wait for the server marketplace catalog sync.```Full details and the release checklist:@@ -122,16 +122,32 @@ The finished app is at## Where to go next<CardGroup cols={2}>- <Card title="Data reference" icon="database" href="/developers/extend/apps/data/overview">+ <Card+ title="Data reference"+ icon="database"+ href="/developers/extend/apps/data/overview"+ >Every field type, relation, and index option.</Card>- <Card title="Logic reference" icon="bolt" href="/developers/extend/apps/logic/overview">+ <Card+ title="Logic reference"+ icon="bolt"+ href="/developers/extend/apps/logic/overview"+ >Cron and database-event triggers, the key-value store, OAuth connections.</Card>- <Card title="Layout reference" icon="table-columns" href="/developers/extend/apps/layout/overview">+ <Card+ title="Layout reference"+ icon="table-columns"+ href="/developers/extend/apps/layout/overview"+ >Page layouts, dashboard widgets, and more UI surfaces.</Card>- <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">+ <Card+ title="Operations"+ icon="rocket"+ href="/developers/extend/apps/operations/overview"+ >CLI, testing, remotes, and CI.</Card></CardGroup>diff --git a/packages/twenty-front-component-renderer/project.json b/packages/twenty-front-component-renderer/project.jsonindex cd11cda9300..a199dffa1f0 100644--- a/packages/twenty-front-component-renderer/project.json+++ b/packages/twenty-front-component-renderer/project.json@@ -107,6 +107,7 @@"{projectRoot}/src/__stories__/showcase/**/*","{projectRoot}/src/__stories__/twenty-ui-gallery/**/*","{projectRoot}/src/__stories__/shared/front-components/**/*",+ "{workspaceRoot}/packages/twenty-sdk/src/front-component-renderer/build/**/*","{workspaceRoot}/packages/twenty-sdk/src/cli/utilities/build/**/*","{workspaceRoot}/packages/twenty-shared/src/front-component-build/**/*","{workspaceRoot}/packages/twenty-shared/vite.bundled-source-plugin.ts"diff --git a/packages/twenty-front/src/pages/settings/applications/tabs/SettingsApplicationRegistrationDistributionTab.tsx b/packages/twenty-front/src/pages/settings/applications/tabs/SettingsApplicationRegistrationDistributionTab.tsxindex 4640fcae2e7..69fe4eff28b 100644--- a/packages/twenty-front/src/pages/settings/applications/tabs/SettingsApplicationRegistrationDistributionTab.tsx+++ b/packages/twenty-front/src/pages/settings/applications/tabs/SettingsApplicationRegistrationDistributionTab.tsx@@ -33,7 +33,7 @@ export const SettingsApplicationRegistrationDistributionTab = ({availableApplicationId: registration.universalIdentifier,});- const publishCommands = [doNotTranslate('yarn twenty app:publish')];+ const publishCommands = [doNotTranslate('twenty app publish')];return (<>diff --git a/packages/twenty-website/src/app-preview/terminal/AssistantResponseSegments.tsx b/packages/twenty-website/src/app-preview/terminal/AssistantResponseSegments.tsxindex cc897b73427..e0083ebf3e9 100644--- a/packages/twenty-website/src/app-preview/terminal/AssistantResponseSegments.tsx+++ b/packages/twenty-website/src/app-preview/terminal/AssistantResponseSegments.tsx@@ -204,7 +204,7 @@ const WRAPUP_PARAGRAPH: StreamingSegment[] = [<InlineCode>vitest run schema.integration-test.ts</InlineCode>,),text(', and '),- node('w-dev', <InlineCode>yarn twenty dev --once</InlineCode>),+ node('w-dev', <InlineCode>twenty app apply</InlineCode>),text('. Reference: '),node('w-docs',diff --git a/packages/twenty-website/src/sections/faq/faq.data.ts b/packages/twenty-website/src/sections/faq/faq.data.tsindex 670885ef793..6742cd323e7 100644--- a/packages/twenty-website/src/sections/faq/faq.data.ts+++ b/packages/twenty-website/src/sections/faq/faq.data.ts@@ -25,7 +25,7 @@ export const FAQ_QUESTIONS: readonly FaqQuestion[] = [},{question: msg`Can developers extend Twenty with code?`,- answer: msg`Yes, with our Apps framework. Scaffold an extension with \`npx create-twenty-app\` and ship custom objects, server-side logic functions, React components that render inside Twenty’s UI, AI skills and agents, views, and navigation, all in TypeScript, deployable to any workspace.`,+ answer: msg`Yes, with our Apps framework. Scaffold an extension with \`npx twenty@latest app init my-app\` and ship custom objects, server-side logic functions, React components that render inside Twenty’s UI, AI skills and agents, views, and navigation, all in TypeScript, deployable to any workspace.`,},{question: msg`Does Twenty work with Claude, ChatGPT, and Cursor?`,