twenty 0.3.0 → 2.48.0

package/CONTRIBUTING.md

@@ -0,0 +1,174 @@
+# Contributing to Twenty CLI
+
+This package is the `twenty` executable in the Twenty monorepo. Its Nx project
+is named `twenty-cli`; its Yarn workspace and npm package are named `twenty`.
+Follow the repository's development instructions and nearby code conventions.
+
+## Build and verify
+
+Run these from the repository root after installing its dependencies:
+
+```bash
+yarn nx build twenty-cli
+node packages/twenty-cli/dist/cli.cjs --help
+yarn nx lint twenty-cli
+yarn exec tsgo -p packages/twenty-cli/tsconfig.json --noEmit
+```
+
+Tests that use real applications or SDK parity references require the repository
+SDK to be built. Its Nx target builds its dependencies:
+
+```bash
+yarn nx build twenty-sdk
+cd packages/twenty-cli
+yarn exec vitest run --maxWorkers=2
+```
+
+For a focused change, pass its test file or directory to `vitest run`. Command
+tests execute the public command runner with local HTTP fixtures. Worker tests
+exercise subprocess output, cancellation and snapshot lifetime. Parity suites
+compare generated source and artifacts against the SDK implementation;
+the SDK is a test reference, not a runtime tooling dependency.
+
+Rebuild `twenty-shared` with `--skip-nx-cache` after switching branches or changing
+shared exports. Generated `dist` directories are not tracked, and stale outputs
+can invalidate dependent test and typecheck results. Use the direct TypeScript
+command above when checking a fix rather than relying on an Nx cache hit.
+
+No live workspace is required for the unit suite. Passing it does not establish
+live authorization, remote upload or server-version compatibility. Exercise
+changed server workflows against a disposable workspace when appropriate.
+
+## Package map
+
+| Location | Responsibility |
+| --- | --- |
+| `src/catalog` | Command definitions, topics and lazy handler loading |
+| `src/commands` | Command orchestration and user-visible results |
+| `src/program` | Argument parsing, target setup, interaction and command lifecycle |
+| `src/config`, `src/target`, `src/oauth` | Saved connections, target selection and authentication |
+| `src/transport` | HTTP/GraphQL requests, proxy routing, limits and cancellation |
+| `src/metadata`, `src/data` | Workspace metadata inspection and record reads |
+| `src/doctor` | Read-only setup and connection diagnostics |
+| `src/app` | Project tooling and application lifecycle, see its [module map](src/app/README.md) |
+| `src/input`, `src/output` | Input parsing, human/JSON/NDJSON output and error contracts |
+| `app-template` | App source, configuration and CLI-based integration-test harness copied by `app init` |
+
+Command definitions are the source for help and `twenty commands`. Keep handlers
+lazy so discovery does not load compiler or app code. Put a workflow's rules in
+its owning module; a command handler should connect parsed input, that module
+and output. Preserve meaningful behavior tests when moving implementation files.
+
+## Application tooling guarantees
+
+The [application module documentation](src/app/README.md) describes each stage.
+Changes must preserve these contracts:
+
+- App definitions execute as trusted code in a disposable worker. The worker
+  contains process exits, filters CLI credentials and captures bounded output;
+  it is not a filesystem or network sandbox. Executable configs stay in the
+  worker, and only serializable requests and results cross IPC.
+- A build's immutable snapshot stays alive until its consumers finish. Uploads
+  verify containment, size and checksums. Failed or cancelled work must release
+  the snapshots it owns without removing another build's files.
+- Apply reports which remote phases completed and whether the outcome is known.
+  Do not retry writes or claim rollback when the server's result is unknown.
+  Each apply uses a fresh plan; approval does not carry across dev revisions.
+- Pull stages source writes and its target-bound baseline together. Ordinary
+  failures restore originals; interrupted workers and failed rollback report
+  uncertainty and retain recovery information. Unsupported definitions remain
+  visible in coverage reports.
+- JSON emits one result envelope. Streaming commands honor backpressure, bound
+  buffering and emit a terminal result or error. Cancellation exits 130 unless
+  the operation has already acknowledged its completed result.
+
+## Packaging
+
+Vite builds the CLI, its worker and lazy chunks into `dist`. It also copies the
+CLI-owned `app-template` there. Chokidar,
+esbuild, tinyglobby and the CLI's TypeScript parser are runtime dependencies;
+other imported libraries are bundled. The parser is separate from the app's
+compiler used for typechecking.
+
+The archive includes the command reference, contributor guide and application
+module READMEs so their relative links also work outside a repository checkout.
+It does not include the CLI's TypeScript implementation or tests.
+
+For packaging changes, run the build and installation checks:
+
+```bash
+yarn nx run twenty-cli:test:package
+```
+
+This runs the binary declared in the workspace's `package.json` directly, packs
+the CLI, and installs the archive with only its production dependencies in a
+temporary directory outside the monorepo. It checks help, offline doctor, app initialization including the
+integration-test harness, and a compiler diagnostic from the installed worker. npm
+registry access is required for installation; the commands do not contact a
+Twenty workspace. Temporary files are removed afterward, and nothing is
+published. CI runs the same target for CLI and dependency changes.
+
+The CLI CI job also runs `scripts/test-app-publish.mjs` after building the CLI
+and SDK. It starts a disposable Verdaccio registry with no upstream registries,
+publishes a fixture with real npm, downloads and inspects the tarball, and checks
+version rejection, incomplete packages and cleanup. On Linux CI the test runs
+inside a network namespace with only loopback enabled, so it cannot reach public
+npm. It uses temporary npm configuration and a local test token.
+
+## Releases
+
+Publish the CLI when its changes warrant a release. A server release does not
+require a CLI release; skip versions when the CLI has no changes worth shipping.
+When publishing, aim to align the CLI version with the corresponding Twenty
+server, SDK and UI version.
+
+Publishing is independent through the `cli/` tag family: `cli/v2.46.0` publishes
+only `twenty@2.46.0`. The tag version must match
+`packages/twenty-cli/package.json`. Bumping the package version alone does not
+publish the CLI.
+
+`app init` pins `twenty-client-sdk`, `twenty-sdk` and `twenty-ui` to the
+`twenty-sdk` version of the commit the CLI was built from. `main` moves
+to the next, unpublished SDK version right after each SDK release:
+
+1. Start from the matching `sdk/vA.B.C` release commit. If a CLI version bump
+   is still needed, make it on a branch from that commit.
+2. Once the SDK, client SDK and UI packages at `A.B.C` are on npm, tag the
+   prepared commit `cli/vA.B.C`.
+3. Run the `Publish npm packages` workflow in `twenty-infra` with that tag as
+   its `ref`. Creating the tag alone does not publish the package.
+
+`yarn npm publish` first runs `scripts/prepublish.mjs`, which needs a fresh
+build and npm registry access. It checks the build first, and fails when the
+executable, worker, lazy chunks or templates are missing, when `dist` was built
+for another version, when one of its CLI runs fails or times out, or when
+`app init` would pin versions that are not on npm. An unreachable registry is
+reported separately from a missing version. The check does not read tags: it
+confirms that the pinned versions are published. Selecting the matching SDK
+release remains a release step.
+
+Once the check passes, the script resolves the built app template's
+dependencies, with the versions that `app init` pinned during the check, using
+the repository's Yarn against the public registry, under a 3-day minimum
+release age that exempts the pinned Twenty packages. It then writes
+`dist/app-template/yarn.lock`. Apps created with `app init` then install exact,
+integrity-checked versions, including for people who enforce a minimum release
+age. The lockfile keeps the template's placeholder name, and the first
+`yarn install` renames that root entry.
+
+The tests of both steps run with `twenty-cli:test:package`. To run the script
+before tagging:
+
+```bash
+yarn nx build twenty-cli
+node packages/twenty-cli/scripts/prepublish.mjs
+```
+
+## App integration tests
+
+`app-template/src/__tests__` supplies the integration-test setup for CLI-created apps.
+It deploys the app before tests and uninstalls it afterward by invoking the
+installed CLI with `--json`. Apps invoke the executable rather than import the
+CLI as a library or add it as a dependency. See the
+[template contract](docs/commands.md#create-an-app) for executable selection and
+the [compiler requirements](src/app/typecheck/README.md) for project setup.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Twenty.com, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,89 @@
 # Twenty CLI
 
-The new command-line interface for [Twenty](https://twenty.com) is coming soon.
+Work with [Twenty](https://twenty.com) from your terminal: connect to workspaces,
+inspect metadata and records, send API requests, and develop applications.
 
-This package does not provide an executable yet. For the currently available CLI,
-use [twenty-sdk](https://www.npmjs.com/package/twenty-sdk).
+## Install
+
+The CLI needs Node.js 24.5 or later.
+
+```bash
+npm install -g twenty
+twenty --version
+```
+
+## Get started
+
+```bash
+twenty doctor --offline
+twenty auth login --url https://acme.twenty.com --use
+twenty metadata object list
+twenty data list companies --limit 5
+twenty open
+```
+
+Replace the example URL with your workspace's address. `--use` makes this
+connection the default, even when another saved connection already is one. Use
+`--remote <name>` to select another saved connection and `--json` for a
+structured result. Saved connections live in `~/.twenty/config.json`.
+
+Browser sign-in is supported on Twenty 2.42 and later. On older servers, sign in
+with an [API key](docs/commands.md#connections-and-authentication) instead.
+
+## Develop an application
+
+App projects pin Yarn 4 in `packageManager`. Run `corepack enable` once so
+`yarn` uses that version; if `corepack` is missing, install it with
+`npm install -g corepack`. These steps use the default connection;
+`twenty auth status` shows which one that is:
+
+```bash
+twenty app init my-app
+cd my-app
+yarn install
+twenty app build
+twenty app apply --create
+twenty app dev
+```
+
+`app init` writes files without installing dependencies. `app build` checks the
+project locally. `app apply --create` registers and installs a new development
+app, uploads its build and synchronizes its metadata. Once registered, inspect
+changes with `twenty app plan` before applying them. `app dev` watches inputs and
+syncs successful builds.
+
+Missing definitions imply remote deletions by default. Pass `--no-delete` to
+preserve them. Object and field deletions require confirmation because they
+also delete stored data. Pull can overwrite local edits; read its
+[reconciliation rules](docs/commands.md#pull-an-app) before using it.
+
+Apps created with `app init` declare the oldest Twenty version they support in
+`engines.twenty`. `app exec` runs functions as the signed-in user, so it needs a
+browser sign-in and Twenty 2.46 or later. With a browser sign-in, `app uninstall`
+also needs Twenty 2.46 or later; on earlier versions, use an API key for it.
+
+## CLI and app dependencies
+
+The CLI is installed globally, separately from each app. Apps keep `twenty-sdk`
+as a development dependency for authoring and build-time APIs, `typescript` for
+checks, and `twenty-client-sdk` when they use a generated API client. Neither
+apps nor SDK packages need `twenty` in their dependencies or devDependencies. In
+CI, install a pinned version with `npm install -g twenty@<version>`.
+
+The CLI owns builds and filesystem operations. It uses the app's installed
+SDK authoring exports and TypeScript compiler. Configuration and project-reference
+errors fail builds. See [build requirements](docs/commands.md#build-and-check-an-app)
+for supported SDK exports and compiler configuration.
+
+## Documentation
+
+- [Command reference](docs/commands.md), authentication, flags, output, permissions
+  and recovery for each workflow.
+- [Contributing](CONTRIBUTING.md), building from source, package structure, tests
+  and releases.
+- [Application tooling](src/app/README.md), module responsibilities and invariants.
+
+Run `twenty commands` for the command inventory or `twenty <command> --help` for
+its arguments and options.
+
+Generated next-step commands use PowerShell on Windows and POSIX shell syntax on macOS/Linux.

package/dist/app-template/.nvmrc

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

package/dist/app-template/.oxlintrc.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript"],
+  "categories": {
+    "correctness": "off"
+  },
+  "ignorePatterns": ["node_modules", "dist"],
+  "rules": {
+    "no-unused-vars": "off",
+
+    "typescript/no-unused-vars": [
+      "warn",
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "typescript/no-explicit-any": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.logic-function.ts", "**/logic-functions/**/*.ts"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "patterns": [
+              {
+                "group": ["twenty-shared", "twenty-shared/*"],
+                "message": "Logic functions must not import from twenty-shared directly. Import runtime types and helpers from `twenty-sdk/logic-function` instead so the logic-function bundle stays minimal."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/dist/app-template/AGENTS.md

@@ -0,0 +1,70 @@
+## Base documentation
+
+- Getting started:
+  - https://docs.twenty.com/developers/extend/apps/getting-started/quick-start.md
+  - https://docs.twenty.com/developers/extend/apps/getting-started/concepts.md
+  - https://docs.twenty.com/developers/extend/apps/getting-started/project-structure.md
+  - https://docs.twenty.com/developers/extend/apps/getting-started/local-server.md
+  - https://docs.twenty.com/developers/extend/apps/getting-started/scaffolding.md
+  - https://docs.twenty.com/developers/extend/apps/getting-started/troubleshooting.md
+- Config:
+  - https://docs.twenty.com/developers/extend/apps/config/overview.md
+  - https://docs.twenty.com/developers/extend/apps/config/application.md
+  - https://docs.twenty.com/developers/extend/apps/config/roles.md
+  - https://docs.twenty.com/developers/extend/apps/config/install-hooks.md
+  - https://docs.twenty.com/developers/extend/apps/config/public-assets.md
+- Data:
+  - https://docs.twenty.com/developers/extend/apps/data/overview.md
+  - https://docs.twenty.com/developers/extend/apps/data/objects.md
+  - https://docs.twenty.com/developers/extend/apps/data/extending-objects.md
+  - https://docs.twenty.com/developers/extend/apps/data/relations.md
+- Logic:
+  - https://docs.twenty.com/developers/extend/apps/logic/overview.md
+  - https://docs.twenty.com/developers/extend/apps/logic/logic-functions.md
+  - https://docs.twenty.com/developers/extend/apps/logic/skills-and-agents.md
+  - https://docs.twenty.com/developers/extend/apps/logic/connections.md
+- Layout:
+  - https://docs.twenty.com/developers/extend/apps/layout/overview.md
+  - https://docs.twenty.com/developers/extend/apps/layout/views.md
+  - https://docs.twenty.com/developers/extend/apps/layout/navigation-menu-items.md
+  - https://docs.twenty.com/developers/extend/apps/layout/page-layouts.md
+  - https://docs.twenty.com/developers/extend/apps/layout/front-components.md
+  - https://docs.twenty.com/developers/extend/apps/layout/command-menu-items.md
+- Operations:
+  - https://docs.twenty.com/developers/extend/apps/operations/overview.md
+  - https://docs.twenty.com/developers/extend/apps/operations/cli.md
+  - https://docs.twenty.com/developers/extend/apps/operations/testing.md
+  - https://docs.twenty.com/developers/extend/apps/operations/publishing.md
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard
+
+## UUID requirement
+
+- All generated UUIDs must be valid UUID v4.
+
+## Common Pitfalls
+
+- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
+- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
+
+## Best practice
+
+It's highly recommended to create new app entities using `yarn twenty dev: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`  |
+
+This helps automatically generate required IDs etc.

package/dist/app-template/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this application are documented in this file.
+
+## 0.1.0
+
+- Initial application scaffolded with `twenty app init`

package/dist/app-template/README.md

@@ -0,0 +1,34 @@
+# My Twenty App
+
+Describe your app in one or two sentences.
+
+## Features
+
+List the top things your app does, for example:
+
+- Feature one
+- Feature two
+- Feature three
+
+## Getting started
+
+Setup instructions live in [SETUP.md](SETUP.md).
+
+## Publishing
+
+The `Publish` workflow (`.github/workflows/publish.yml`) publishes the app to npm with provenance using [npm trusted publishing](https://docs.npmjs.com/trusted-publishers). To publish:
+
+1. On npmjs.com register this repository as a trusted publisher of your package, pointing at the `publish.yml` workflow.
+2. Bump the version in `package.json`, then push a version tag (e.g. `git tag v1.0.0 && git push --tags`) or run the workflow manually from the Actions tab.
+
+Publishing with provenance is also how you prove ownership when claiming your app in a Twenty marketplace.
+
+## Changelog
+
+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)
+- [Discord](https://discord.gg/cx5n4Jzs57)

package/dist/app-template/SETUP.md

@@ -0,0 +1,47 @@
+# Setup
+
+Follow these steps to get your app running locally.
+
+## Prerequisites
+
+- Node.js (version specified in `.nvmrc`)
+- Yarn 4
+- Docker (to run the local Twenty server)
+
+## Steps
+
+1. Install dependencies:
+
+   ```bash
+   yarn install
+   ```
+
+   The committed `yarn.lock` pins exact, integrity-checked versions, so this
+   resolves nothing from the registry.
+
+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: `tim@apple.dev` / `tim@apple.dev`.
+
+## 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).

package/dist/app-template/github/workflows/cd.yml

@@ -0,0 +1,42 @@
+name: CD
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [labeled]
+
+permissions:
+  contents: read
+
+env:
+  TWENTY_DEPLOY_URL: http://localhost:2020
+
+concurrency:
+  group: cd-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy-and-install:
+    if: >-
+      github.event_name == 'push' ||
+      (github.event_name == 'pull_request' && github.event.label.name == 'deploy')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Deploy
+        uses: twentyhq/twenty/.github/actions/deploy-twenty-app@main
+        with:
+          api-url: ${{ env.TWENTY_DEPLOY_URL }}
+          api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}
+
+      - name: Install
+        uses: twentyhq/twenty/.github/actions/install-twenty-app@main
+        with:
+          api-url: ${{ env.TWENTY_DEPLOY_URL }}
+          api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}

package/dist/app-template/github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: {}
+
+permissions:
+  contents: read
+
+env:
+  TWENTY_VERSION: latest
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Spawn Twenty test instance
+        id: twenty
+        uses: twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main
+        with:
+          twenty-version: ${{ env.TWENTY_VERSION }}
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: yarn
+
+      - name: Install Twenty CLI
+        run: npm install -g twenty@CLI-VERSION-TO-BE-GENERATED
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Typecheck
+        run: yarn typecheck
+
+      - name: Unit tests
+        run: yarn test:unit
+
+      - name: Run integration tests
+        run: yarn test
+        env:
+          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
+          TWENTY_API_KEY: ${{ steps.twenty.outputs.api-key }}

package/dist/app-template/github/workflows/publish.yml

@@ -0,0 +1,52 @@
+# Publishes the app to npm with provenance (npm trusted publishing).
+#
+# One-time setup:
+# 1. On npmjs.com open your package > Settings > Trusted Publisher and register
+#    this repository and this workflow file (publish.yml).
+#    See https://docs.npmjs.com/trusted-publishers
+# 2. Push a version tag (e.g. `git tag v1.0.0 && git push --tags`) or run the
+#    workflow manually from the Actions tab.
+#
+# Publishing with provenance certifies which GitHub repository the package is
+# built from. This is also how you claim ownership of your app in a Twenty
+# marketplace: the claim flow verifies you own the GitHub account or
+# organization the provenance points to.
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  # Required for npm trusted publishing (OIDC provenance).
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm
+        # Trusted publishing requires npm 11.5.1 or later.
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Publish to npm
+        # Uncomment if publishing from a private source repo: npm rejects
+        # OIDC provenance for private repos
+        # env:
+        #   TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
+        run: yarn twenty app:publish