twenty 0.2.0 → 2.46.0

package/package.json

@@ -1,28 +1,51 @@
 {
   "name": "twenty",
-  "version": "0.2.0",
-  "description": "Locates the city/region of a given IP address",
-  "main": "index.js",
+  "version": "2.46.0",
+  "description": "The Twenty command line.",
+  "homepage": "https://twenty.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/scottwrobinson/twentyjs.git"
+    "url": "git+https://github.com/twentyhq/twenty.git",
+    "directory": "packages/twenty-cli"
   },
-  "keywords": [
-    "cli",
-    "location",
-    "ipinfo",
-    "tools"
+  "bugs": {
+    "url": "https://github.com/twentyhq/twenty/issues"
+  },
+  "license": "MIT",
+  "bin": "dist/cli.cjs",
+  "files": [
+    "dist",
+    "docs/commands.md",
+    "CONTRIBUTING.md",
+    "src/app/**/README.md"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "npx rimraf dist && npx vite build",
+    "prepublish": "node scripts/check-publish.mjs && node scripts/generate-template-lock.mjs"
   },
-  "author": "Scott Robinson <s.w.robinson@gmail.com> (http://stackabuse.com)",
-  "license": "MIT",
-  "dependencies": {
-    "request": "^2.67.0",
-    "yargs": "^4.2.0"
+  "engines": {
+    "node": "^24.5.0"
+  },
+  "devDependencies": {
+    "@sniptt/guards": "^0.2.0",
+    "@types/lodash.startcase": "^4",
+    "@types/node": "^24.0.0",
+    "@types/semver": "^7.5.8",
+    "cjs-module-lexer": "^2.2.0",
+    "commander": "^14.0.3",
+    "lodash.startcase": "^4.4.0",
+    "semver": "7.6.3",
+    "twenty-client-sdk": "2.46.0",
+    "twenty-shared": "0.0.0",
+    "undici": "^7.29.0",
+    "uuid": "^13.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   },
-  "bin": {
-    "twenty": "./bin/twenty"
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "esbuild": "^0.28.1",
+    "tinyglobby": "^0.2.15",
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/app/README.md

@@ -0,0 +1,43 @@
+# Application tooling
+
+See [Contributing](../../CONTRIBUTING.md) for package setup and tests, and the
+[command reference](../../docs/commands.md) for user-visible behavior.
+
+The `twenty` CLI owns filesystem operations, source loading, build, typecheck,
+watching, pull and deployment. Apps use `twenty-sdk` to define application
+metadata and runtime behavior. They do not import or depend on the CLI, which
+is normally installed globally.
+
+| Module                                   | Responsibility                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `project`                             | Locate the app and resolve its installed SDK and Node requirements   |
+| `deployment`                          | Preview metadata changes, approve them, upload snapshots and sync    |
+| [source](source/README.md)               | Discover and evaluate trusted app definitions in a disposable worker |
+| [manifest](manifest/README.md)           | Construct and validate metadata, compile translations                |
+| [bundles](bundles/README.md)             | Build artifacts and hold immutable snapshots for consumers           |
+| [typecheck](typecheck/README.md)         | Check source and configuration with the app's TypeScript compiler    |
+| [client](client/README.md)               | Invoke the app's installed client SDK generator                      |
+| [pull](pull/README.md)                   | Reconcile remote metadata with source and a target-bound baseline    |
+| [add](add/README.md)                     | Create starter definitions without replacing existing files          |
+| [dev](dev/README.md)                     | Watch build inputs and schedule builds and remote apply              |
+| [exec](exec/README.md)                   | Execute an installed logic function                                  |
+| [function-logs](function-logs/README.md) | Stream application function logs                                     |
+
+The worker isolates process exits, captures bounded output, filters inherited
+CLI credentials and supports cancellation. It runs trusted developer code and
+is not a security sandbox. Configurations containing functions stay inside the
+worker; only serializable requests, results and diagnostics cross IPC.
+
+Snapshots retain files until their consumers finish. Uploads verify containment,
+size and checksums. Pull and scaffolding stage writes before exposing them to
+file watchers. Keep these guarantees when simplifying implementation details.
+
+## Package boundaries
+
+The CLI imports the app's public SDK authoring exports and invokes its installed
+client SDK generator. The [typecheck documentation](typecheck/README.md) describes
+compiler resolution and project requirements.
+
+Parity tests compare generated source, manifests and bundles with the repository
+SDK. Command failure and cancellation tests inject tooling fixtures into a bundle
+of the production worker; real-app tests exercise its compiler and bundler.

package/src/app/add/README.md

@@ -0,0 +1,69 @@
+# App definition scaffolding
+
+The templates create object, field, logic-function and front-component
+definitions. Filenames and logic-function/front-component names use kebab-case.
+Object and field metadata names keep the entered spelling; display labels use
+the same helper as app init.
+
+## Contract
+
+- `twenty app add [entity]` accepts `object`, `field`, `logic-function` and
+  `front-component`. A human terminal can supply omitted values interactively.
+  JSON, CI, redirected stdin and `--no-input` never prompt; missing required or
+  inapplicable options exit 2. Labels default to the name; fields default to
+  `TEXT`.
+- `--path` selects an app, like the other CLI app commands. Files go under the
+  selected app's `src/objects`, `src/fields`, `src/logic-functions` or
+  `src/front-components`. Custom output directories are not supported.
+- Parent and relation endpoint identifiers must be valid universal UUIDs. No
+  workspace lookup verifies ownership or existence. Relations require reviewing
+  both endpoints; this generator creates only the requested standalone field.
+- Objects accept `--create-view`, `--create-navigation-menu-item` and
+  `--create-page-layout`. Each flag opts into that definition; page layouts also
+  create the fields view used by their Fields widget. The list view and fields
+  view reuse the object's name field. Fields views also include the SDK's
+  generated audit fields, resolved using the application's universal identifier.
+  With no creation flags, human interactive mode offers all three together,
+  defaulting to No. Explicit creation flags bypass that question. Noninteractive
+  modes never ask and create only explicitly selected companions. All prompts
+  complete before any files are written, including on cancellation.
+- Node's `randomUUID` creates version 4 identifiers. The CLI TypeScript printer
+  escapes authored strings, including quotes, backslashes and line breaks.
+- App discovery, SDK compatibility and application identity reuse the CLI's
+  worker boundary. Identity loading evaluates trusted app code in a disposable
+  worker; it is not a security sandbox. The command makes no workspace requests
+  and does not require authentication.
+- Destination paths reuse pull's containment and symlink checks. All destinations
+  are checked before writing and all files are staged beside their destinations
+  before exclusive linking, including when source directories are mounted on
+  different filesystems.
+  Existing or concurrently created files are never replaced. Failure or
+  cancellation before all links complete rolls back the links already created;
+  files replaced by another process are preserved. Incomplete rollback reports
+  remaining app-relative paths. Completion wins over late cancellation. Cleanup failure
+  after success warns and reports the remaining temporary directory. Empty
+  parent directories can remain after failure or cancellation. Exclusive atomic
+  creation requires a filesystem supporting hard links; unsupported filesystems
+  fail instead of falling back to a potentially partial destination write.
+- Path validation rejects existing symbolic links. It cannot prevent another
+  local process from replacing a parent directory between validation and writing.
+- JSON reports app-relative `createdPaths`. There is no overwrite mode and no
+  editing or registration of existing definitions. Standalone view, layout and
+  navigation item generators are not supported.
+
+These are starter definitions, not a deployment validator. Review type-specific
+settings, relation endpoints, handlers and components, then build and plan the
+app. Successful generation does not imply the server will accept the metadata.
+
+## Verification
+
+`add-template-parity.spec.ts` compares generated source with the repository SDK,
+normalizing random UUIDs while preserving their reuse. It covers every field type
+and both runtime templates. Additional tests cover escaped strings, invalid
+identifiers, destination conflicts and cancellation.
+
+View and navigation templates are deliberately limited to object companions:
+fully populated fields and an object-target navigation item, without the SDK
+CLI's placeholder and unrelated view/link/folder variants. Generated identifiers
+and references are checked by the app-add command tests; record page layouts
+also retain SDK source parity.

package/src/app/bundles/README.md

@@ -0,0 +1,85 @@
+# Bundles and snapshots
+
+The CLI owns application bundling and immutable snapshot lifecycle. The internal
+`bundleSnapshot` worker request builds and holds or releases a snapshot under
+`.twenty/cli/snapshots/build-*`. The [typechecker](../typecheck/README.md) uses the
+app's own TypeScript compiler. Build, plan, apply and uninstall use this pipeline.
+Worker requests are internal, not a public API or a way to bypass build checks.
+
+See the [app tooling overview](../README.md) for package ownership.
+
+## Contract
+
+Logic functions use an ESM/CJS banner, external modules and define stubs.
+Front components use JSX wrappers, remote-DOM transformation, optional
+preact aliases, bundled CSS injection, static shared-dependency export discovery
+and live-binding shims. The app's translation catalogs are embedded in the bundles.
+Dependency discovery does not execute package initialization code. CommonJS
+named exports must be statically detectable; packages that compute export names
+at runtime can be consumed through their default export.
+
+The bundler collects source and dependency files, public and generated assets,
+and the README, and updates the manifest's artifact checksums. Snapshot copies
+dereference symlinks. Each upload artifact records its role, byte size and
+SHA-256 hash. README and source maps are included in the snapshot but are not
+upload artifacts. The content hash combines the sorted artifact paths, roles and
+hashes with the exact manifest bytes.
+
+Each build has its own directory and lease. Release removes only a snapshot held
+by that worker. Failed and cooperatively cancelled builds remove their temporary
+directory. Forced worker termination can leave a snapshot behind. Cleanup only
+removes snapshots owned by the current build.
+
+## Implementation
+
+- Source loading, manifest generation, translations and filesystem helpers are
+  shared with the other CLI app operations. The [dev session](../dev/README.md)
+  observes the build's inputs and retains immutable copies for remote apply.
+- The define stub reads `twenty-sdk/define` from the app's installed SDK. Factories
+  become no-op validators, plain-data exports retain their values, and other
+  exports use proxy stubs. Runtime constants match the SDK the app uses.
+- `sharp` is optional and resolved from the app. It is not a CLI dependency.
+  When unavailable, cover generation warns and the build continues. Vite embeds
+  the backdrop PNG as a data URI so it works in the standalone package.
+- `compileApplication` runs the CLI typecheck after bundling, using the compiler
+  resolved from the app.
+- Workers run from the selected app directory, so invoking the CLI from a
+  parent or nested directory produces the same bundle paths, bytes and hashes.
+  SDK parity references run from the app root as well.
+- Upload validation accepts only snapshots inside the selected app's
+  `.twenty/cli/snapshots`, with path containment and per-file hash checks.
+- The internal worker reuses the source SDK gate, credential filtering, output
+  capture, cancellation and held-snapshot release flow, and stops esbuild after
+  building. Public app commands share this worker lifecycle and its
+  `ToolingResult` contract.
+
+## Verification
+
+After building shared, SDK and UI dependencies, from `packages/twenty-cli`:
+
+```bash
+node ../../node_modules/vitest/vitest.mjs run --config vitest.config.ts --maxWorkers=1 src/app/snapshots src/app/bundles src/app/__tests__/resolve-snapshot-directory.spec.ts src/commands/app/__tests__/app-real-sdk.spec.ts
+```
+
+The parity suite builds all five repository fixtures and a fresh CLI-created app
+through the SDK reference and the production CLI worker. The app has a copy of
+the real authoring SDK without its build/CLI exports or implementation files.
+Successful builds preserve manifest configuration and artifact paths/roles.
+Non-frontend files are compared byte for byte, except for `manifest.json` and
+source maps. Frontend bundle bytes and checksums are allowed to differ: dedicated tests verify preserved
+string literals, resolved CSS assets and live shared-dependency bindings. Every
+CLI artifact's size/checksum and the snapshot content hash are checked against
+the actual bytes. Tests also verify the manifest references for function, component
+and shared-dependency bundles, and compare the serialized manifest with the
+worker's manifest result. The invalid fixture fails in both
+pipelines. The fresh CLI template's test setup typechecks with an authoring-only SDK.
+
+Source-map comparisons for unchanged bundles resolve paths against each map's
+directory and exclude the define stub's generator banner from `sourcesContent`.
+
+Additional tests cover optional covers, project SDK constants, baked translations
+and CSS, README selection, immutable symlink copies, concurrent snapshots,
+release ownership, failed/cancelled builds and failed snapshot consumers. The
+build/apply contract runs CLI snapshots against a local HTTP fixture, including
+uploads, sync, pull-base recording, release and client generation. It does not contact
+a live Twenty workspace.

package/src/app/client/README.md

@@ -0,0 +1,62 @@
+# Application client generation
+
+The CLI calls `replaceCoreClient` from the app's installed
+`twenty-client-sdk/generate`. See the [app tooling overview](../README.md) for
+package boundaries. The package manifest is read through `readJsonObject`;
+missing or malformed JSON and incorrect package names produce an expected-package
+`CLIENT_GENERATION_FAILED` error.
+
+Public `app apply` invokes the generator through the internal
+`generateSourceClient` worker request.
+
+## Package and output ownership
+
+The app must have `node_modules/twenty-client-sdk/package.json` with the expected
+package name. Resolution does not search workspace ancestors, avoiding writes
+to a hoisted-only installation shared by other apps. Package-manager symlinks
+are followed, so a linked installation can still be shared.
+
+Resolve `twenty-client-sdk/generate` from this package and require the entry to
+belong to the same real package directory. It must export a callable
+`replaceCoreClient`. This keeps the generator and the client it writes into on
+the same installed version, with no fallback to the CLI's own client SDK.
+
+The output layout is `dist/core/generated`, `dist/core.mjs` and
+`dist/core.cjs` inside that installation. Source files and the metadata client
+remain unchanged. Neither apps nor SDK packages depend on the CLI. The client
+SDK's generator dependencies remain part of the app's installed client package.
+
+## Failure and cancellation
+
+The worker requires a non-empty schema and an absolute app path. Failures use
+`CLIENT_GENERATION_FAILED` / `CANCELLED` results. Missing or incompatible local
+packages fail before invoking the generator. The generator rejects
+invalid schemas without replacing the installed bundles.
+
+Generation is not transactional. A generator failure can leave partial changes;
+the wrapper reports that failure even if cancellation was requested meanwhile.
+The generator has no cancellation parameter, so the wrapper waits for it to
+settle and then checks the signal. Forced worker termination can interrupt file
+writes. The operation does not roll back partial writes.
+
+## Verification
+
+From `packages/twenty-cli`, after building the shared, SDK and client SDK:
+
+```sh
+node ../../node_modules/vitest/vitest.mjs run --config vitest.config.ts src/app/client src/commands/app/__tests__/app-real-sdk.spec.ts --maxWorkers=1
+```
+
+Parity runs the SDK reference and the production CLI worker against
+the same schema and app path, comparing every generated source file and both
+compiled bundles byte for byte. Reusing the path keeps esbuild's source-path
+comments identical without normalizing file contents. The app has its own client
+SDK and no application SDK. The generated CommonJS client is loaded to verify
+its `CoreApiClient` export.
+
+Other cases cover a missing or hoisted-only package, invalid manifests and
+schemas, missing exports, a non-callable API, selection of the app's generator,
+pre-cancellation, in-flight cancellation and preserved failures/partial writes.
+The local HTTP apply contract exercises CLI client
+generation, along with snapshot upload, synchronization, pull-base recording
+and release. No live workspace is contacted.

package/src/app/dev/README.md

@@ -0,0 +1,35 @@
+# App development session
+
+The parent owns observation and two bounded scheduling lanes: one build worker
+and one remote apply. `runDevLoop` keeps only the latest pending snapshot. Every
+snapshot is released once, including superseded builds and cancellation; the
+active apply retains its files until its reads settle. The skip key is the last
+acknowledged remote content hash, cleared after a failed apply.
+
+`buildDevSnapshot` copies declared, size/SHA-256-verified artifacts into a fresh
+`dev-*` directory while the compiler's snapshot lease is held. The worker then
+releases its own snapshot and exits, so retained builds do not retain compiler
+heaps. At most three snapshot directories exist for an active session: in-flight
+apply, compiler source, and its copy. No hard links or mutable output tree.
+
+Input collection is private worker metadata, absent on ordinary build requests.
+It observes esbuild loads/resolution parents, static-file copies and TypeScript
+reads. Missing TypeScript package-scope probes cannot expand watching into
+unrelated ancestor directories. Inputs have stamps captured before reads; after
+attaching the watcher, changed stamps invalidate the result. A successful graph
+replaces the previous graph; a failure watches the last successful graph plus
+only that attempt's inputs. External directory observation is shallow.
+
+`applyAppBuild` handles remote operations. Dev supplies a
+revision-specific approval signal and a check immediately before the first
+write. Once writes start, a newer build does not cancel those writes. Client
+generation pauses compilation and invalidates pending builds; its successful
+input key plus output stamps prevent generation loops. A failure after client
+writes start ends the session. Normal compilation failures keep watching;
+abnormal worker exits and watcher failures require restart.
+
+There is no incremental compiler cache or package-manager dependency watcher.
+Arbitrary app-code filesystem reads, concurrent independent dev processes,
+and SIGKILL recovery are outside this
+session's guarantees. See the [command reference](../../../docs/commands.md#develop-an-app) for
+user-visible limits.

package/src/app/exec/README.md

@@ -0,0 +1,48 @@
+# CLI app function execution
+
+The command selects one deployed function from the
+local app's identifiers, executes it once with a payload, and reports status,
+duration, data, error and logs. Name matching is exact. Hooks select their
+function identifier; executing an uninstall hook does not uninstall the app.
+A non-SUCCESS result exits with failure. It executes deployed code, so local
+edits must be synced with apply or dev first.
+
+## Contract
+
+- Flags follow the space-separated command surface and kebab-case convention:
+  `app exec --name`, `--universal-identifier`, `--post-install`, `--pre-install`
+  or `--uninstall-hook`. Exactly one selector is required.
+- The CLI keeps no saved build manifest. It uses the `buildManifest`
+  worker to load definitions with the app's authoring SDK, without bundling or
+  typechecking. Worker output becomes diagnostics; credentials are not passed to it.
+- Function selection checks both the local manifest identifiers and the remote
+  installed application's ID. The `findOneApplication` lookup prevents
+  copied or stale identifiers from selecting another installed app's function.
+  This needs `APPLICATIONS` in addition to execution's `WORKFLOWS` permission.
+- The current server requires a user-bound token for execution. Browser-login
+  OAuth remotes are supported; API-key targets fail before loading app source.
+  The server still decides which functions that user can run: workspace custom
+  app functions, functions exposed as workflow actions, or functions from an
+  app registered by this workspace. The CLI does not bypass those checks.
+- Payloads use the JSON-object input reader: inline JSON, `@file` or
+  `-` for stdin, default `{}`. Non-object values are rejected.
+- Human output escapes terminal controls. JSON success includes function/app
+  identity, status, `durationMilliseconds`, data, logs, error and diagnostics.
+  A completed non-SUCCESS result exits 1 with `EXECUTION_FAILED` and retains
+  that information in `error.details`, with `outcome: "completed"`. A missing
+  function exits 4; ambiguous selection exits 6; bad input exits 2.
+- The execution request deadline is the deployed function's `timeoutSeconds`
+  plus the transport's 60-second allowance. Its HTTP dispatcher header/body
+  deadlines use the same value, avoiding Node's default five-minute cutoff.
+  Other commands use their own deadlines and lazy transport loading.
+  Proxies and the server can still close a request earlier.
+- Execution is never retried. Acknowledged authentication, permission,
+  not-found and input/validation rejections have `outcome: "not-started"`.
+  Transport failure, cancellation, internal server error or an invalid response
+  after submission have `outcome: "unknown"`: execution may still be running.
+  Ctrl+C exits 130 and cannot stop the server-side function or undo its effects.
+
+Command tests use the public command runner and real HTTP metadata transport,
+with controlled worker results. They cover selection, application binding,
+payloads, returned errors, rejection/unknown outcomes, cancellation and no
+replay. These tests do not establish live workspace authorization or execution.

package/src/app/function-logs/README.md

@@ -0,0 +1,44 @@
+# CLI app function logs
+
+The command subscribes to POST `/metadata`,
+`logicFunctionLogs(input: LogicFunctionLogsInput!)`, application universal
+identifier and optional exact function name or universal identifier. It receives
+future completed-execution output, not history or per-line execution progress.
+Names can repeat within one app; name selection is a filter matching all of them.
+
+## Contract
+
+- `app logs` uses the CLI app-identity worker. Only the app definition is needed;
+  no function bundles, full manifest build or generated client is required. Source
+  diagnostics use CLI output, and target credentials stay outside the worker.
+- The CLI target supplies OAuth or API-key credentials, environment proxy
+  routing and cancellation. Server authorization requires `WORKFLOWS`,
+  workspace scoping and per-payload application access checks. There is no
+  execution mutation, app registration or workspace audit-log query.
+- The selection requests nullable `name` and `universalIdentifier` fields. Server
+  schemas rejecting only these fields trigger one explicit, warned fallback to
+  `{ logs }`, before any record has been emitted. Unrelated validation,
+  authorization, network and execution errors are never retried. An explicit
+  filter provides that identity if the server cannot; unknown values stay null.
+- A pull-driven reader uses the GraphQL `next`/`complete` SSE protocol,
+  awaits output and reads the next
+  frame only when the consumer is ready. It handles comments, multiline data,
+  split UTF-8 and LF/CRLF/CR framing. Each frame is capped at 16 MiB; the session
+  has no total byte cap. Reader locks and HTTP requests are released on exit.
+- Setup has a 60-second deadline. After setup there is no whole-session timer;
+  the HTTP body's 60-second idle deadline detects missing heartbeats. Yoga sends
+  comments every 12 seconds in production. Undici suspends its body deadline
+  while the body is paused for backpressure and refreshes it on resume.
+- There is no automatic reconnect or replay. EOF without `complete`, broken
+  JSON or records, redirects, oversized frames and network failures stop the
+  command. Errors retain `recordCount`; network failures explain the gap.
+  Explicit server completion exits 0, Ctrl+C exits 130. Human text escapes
+  terminal control characters; NDJSON emits start, connection progress, records
+  and a final result/error. A compatibility fallback may establish two
+  connections and therefore emit two connection progress events.
+
+Tests cover the public command with a real local HTTP transport, duplicate-name
+filters, compatibility failures, proxy routing, per-frame bounds, output
+backpressure, idle heartbeats, stalled connections, completion and cancellation.
+These tests verify protocol behavior, not live workspace authorization or
+execution.

package/src/app/manifest/README.md

@@ -0,0 +1,74 @@
+# Manifest generation
+
+The manifest builder constructs and validates metadata and compiles translations
+for build, plan and apply. The worker evaluates definitions through
+[app/source](../source/README.md); bundling and final artifact checksums belong to
+[app/bundles](../bundles/README.md).
+
+See the [app tooling overview](../README.md) for package ownership.
+
+## Contract
+
+The builder discovers definitions and assets, derives default object fields and
+permission identifiers, infers logic-function input schemas, resolves lifecycle
+hooks, reads the README and validates entity relationships, identifiers, role
+permissions and conditional availability. Manifests are sorted and carry
+checksum placeholders that the bundler replaces with final artifact checksums.
+
+`package.json`'s `engines.twenty` sets
+`application.requiredServerVersionRange`, with surrounding whitespace trimmed;
+an absent or empty value becomes `null`. No CLI version is substituted. The
+builder reports package dependency warnings and validates empty lockfiles.
+
+Translation compilation reuses the locale catalog helpers shared with
+pull. It preserves the distinction between no locale directory (`undefined`)
+and an empty one (`{}`), context-dependent message IDs, authored-over-compiled
+precedence, orphan compiled translations, collision handling and skipped-file
+warnings. It reads catalogs without rewriting them.
+
+Select options without an `id` receive a deterministic ID from their label and
+field identifier. Keep an explicit `id` when changing an option's label or value,
+so existing view filters continue to reference the same option. Duplicate option
+IDs fail validation. Pulled options already carry their server IDs.
+
+## Implementation
+
+- Definition discovery, detection and evaluation reuse `app/source`, including
+  its source and ignore globs and validation-result shape check.
+- Source and public-asset discovery is sorted so warning, error and entity file
+  order is deterministic.
+- The loader result accepts a compile-time config type, with the same runtime
+  shape check. Config types describe the authoring values consumed by the builder.
+  Handler parameters use `never` and return `unknown`; front components expose
+  only the `name` consumed here. The builder never calls those callbacks.
+- The version helper requires an explicit app path; the process working directory
+  cannot choose another app's version.
+- Filesystem reads use Node and the CLI `pathExists` helper. The JSON reader
+  propagates parse errors.
+- The worker resolves the app's authoring SDK with the source compatibility check,
+  returns structured errors and warnings, checks cancellation between phases and
+  stops esbuild before exiting. It uses credential filtering,
+  bounded output capture and cancellation/termination behavior. It does not hold
+  a snapshot or write build state.
+
+## Verification
+
+From `packages/twenty-cli`, after building the repository SDK, shared and UI
+packages:
+
+```bash
+node ../../node_modules/vitest/vitest.mjs run --config vitest.config.ts --maxWorkers=1 src/app/manifest/__tests__/manifest-parity.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 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.

package/src/app/pull/README.md

@@ -0,0 +1,28 @@
+# CLI application pull
+
+Pull reconciles the server's application export with local definitions and a
+target-bound baseline. It preserves unsupported and local-only entities, reports
+overwritten local edits, and commits source changes and the new baseline as one
+transaction. Source generation and translation behavior are covered by parity
+and reconciliation tests.
+
+See the [app tooling overview](../README.md) for package boundaries.
+
+## Contract
+
+- Source scanning stays inside the disposable CLI worker so configs containing functions are never serialized through IPC. Only the server export and report cross that boundary. Selected credentials are removed from the worker environment. App source is trusted developer code, not sandboxed code.
+- The wire/export and baseline boundary check identity and envelope fields, not every metadata collection. `toPullManifest` is the single explicit assertion into the typed writers, preserving their trust in the server schema. Missing/null object and field collections are consumed with `?? []`, like the other collections. Malformed entity contents can still make reconciliation fail before writing. We do not duplicate the server's schema.
+- The baseline file is an envelope whose `manifest` member is an `ExportedManifest`. Reconciliation walks arrays generically without maintaining a second collection list. Unrecognized collections and non-array metadata survive; protected or unreconciled definitions retain their prior baseline entries.
+- `preparePullEntities` resolves the source layout once for current and baseline entities. Planning, overwrite reporting and nested-definition protection consume these prepared entities. A definition can leave a parent only when another retained or written file contains it, or its remote deletion is confirmed.
+- Fields already declared with `defineField` stay in their existing files, even when the server exports them inside an object. Object generation excludes those fields; baseline comparisons use the same source layout. Pull also removes duplicate inline copies left in object files, while retaining the standalone definitions.
+- Before destination writes, `assertPullSdkExports` checks the actual imports emitted by the writer against the app's SDK. It checks export presence, not every config shape; run typecheck to validate the generated definitions against the installed SDK.
+- Temporary files and the baseline live under `.twenty/cli`. Apply and pull share `createPullBaseWrite` as the serializer. The baseline is bound to the API URL, workspace UUID and application UUID. Pull stages it with mode 0600 and writes it after the source files.
+- The baseline can carry `sourceFingerprints`, a SHA-256 per app-relative source and locale file. Apply captures them before building. Pull reports an overwritten local change when a file it rewrites or deletes no longer matches its fingerprint. Without a fingerprint it compares the file with the writer's rendering of the baseline, which is reliable only for source produced by that writer. Pull carries fingerprints forward, updating the files it writes and dropping the ones it deletes.
+- Ordinary I/O failures restore originals. Cancellation is checked before committing the staged plan, not halfway through it. An acknowledged successful commit wins over cancellation. The parent can forcibly kill an unresponsive worker after its grace period, so an unacknowledged result has outcome `unknown`, never a claim that rollback succeeded. Failed rollback retains backups and reports their directory; failure to clean up after a completed commit has outcome `pulled`.
+- Human reporting uses CLI terminal escaping, machine reporting contains the full coverage and path lists, and gaps warn without stopping successful writes. Unknown coverage status strings remain visible. Pull does not prompt for approval or require a clean Git checkout; remote changes overwrite conflicting local edits and are included in the report.
+
+Translation string extraction uses the CLI's TypeScript parser. Traversal, static-string rules, whitespace normalization and deduplication are checked against the SDK reference by parity tests. It does not depend on ts-morph or load parser tooling for help and command discovery.
+
+Pull accepts metadata exports with `files: []` and refuses nonempty source/dependency-file exports. It does not restore package files, generate the typed client or write logic-function/front-component source. Export responses have a 16 MiB cap. Pull does not modify the workspace.
+
+Tests cover writers, planning and reconciliation. Command tests build the actual Vite worker, exercise an authoring-only SDK, local mock HTTP, credentials/output isolation, SDK export refusal and forced termination after the first destination write. The repository SDK tests cover canonical generated definitions, nested coverage, translation preservation, target mismatch, overwrite reporting and rollback.

package/src/app/source/README.md

@@ -0,0 +1,33 @@
+# App source loading
+
+This CLI-owned source loader powers `twenty app pull` and the [manifest builder](../manifest/README.md) used by public build, plan and apply commands.
+
+Package boundaries are documented in the
+[app tooling overview](../README.md).
+
+## Boundary
+
+`readAppIdentity` checks the installed SDK without importing it, then evaluates the application's definition in a disposable CLI worker. Source is trusted executable developer code. The child contains exits, captures bounded output and can be killed on cancellation; it is not a filesystem or network sandbox. Selected workspace credentials are removed from its environment by the worker launcher.
+
+`scanProjectSourceFiles` stays inside the worker. Its configs may contain functions and React components, so reconciliation runs in that same worker rather than send configs over JSON IPC. Only the application UUID, display name and diagnostics cross the identity boundary.
+
+## Compatibility
+
+- The app supplies its own `twenty-sdk`, version `>=1.23.0`, with resolvable `twenty-sdk/define` and `twenty-sdk/front-component` entry points. The installed SDK's Node requirement is checked.
+- There is no upper SDK version cap. Every evaluated definition must return the public `ValidationResult` shape: boolean `success`, object `config`, string-array `errors`, and optional string-array `warnings`. An incompatible shape fails with `SDK_SOURCE_UNSUPPORTED`. This validates the loader contract, not every future SDK behavior.
+- The CLI owns esbuild, its TypeScript parser and tinyglobby as runtime dependencies. These load only for source operations. The app does not need to install TypeScript for source loading. Build and typecheck use the project's compiler separately.
+- The pull writer separately checks the authoring exports its generated files use; this loader floor does not establish that every SDK since 1.23 supports all current manifest collections.
+
+## Source contract
+
+Source discovery covers root and nested `.ts`/`.tsx` files, excluding declarations, `node_modules`, `dist` and `.twenty`. Only a direct top-level `export default defineX(...)` is classified as a definition. Aliases, namespace calls and variable re-exports remain unsupported. Helpers reserve their paths without being evaluated on their own; imported helpers run as dependencies of a definition.
+
+Definitions are bundled using the app's tsconfig and imports, then evaluated with a require rooted at the app. React resolves from the app. UI and generated-client imports use extraction stubs; these are not working UI or client implementations. CSS imports are ignored and conditional-availability expressions are transformed for extraction.
+
+An ordinary extraction failure marks a scanned definition unreadable, retaining its path so reconciliation can avoid overwriting it. SDK validation errors leave the config available for reporting. Reading identity evaluates only application definitions, rejects duplicate or invalid application UUIDs, and returns `null` when no application is declared.
+
+The loader checks SDK compatibility, validation-result shape and cancellation between files. Discovery is sorted: the loader, the identity reader and the scanner share `listApplicationSourceFiles`, so results do not depend on filesystem timing. Detection uses the function name rather than its import origin: a local helper named `defineObject`, for example, must be renamed if it returns an incompatible shape. Such a mismatch fails the scan. Source rewriting and reconciliation live in the adjacent `pull` module.
+
+## Verification
+
+Run the source-loader, SDK-resolution and worker tests with the CLI Vitest configuration. The repository-SDK fixture requires its existing SDK/UI/shared artifacts to be built, as do the other CLI app tests. Worker tests use an authoring-only SDK without a project compiler, exercise output and credential isolation, and cover source exits and cancellation.