Skip to content

The open alternative to Salesforce, designed for AI.

fix(cli): guide app changes through plan and apply (#27414)

Weiko51d22bd62486
diff --git a/packages/twenty-cli/CONTRIBUTING.md b/packages/twenty-cli/CONTRIBUTING.md
index 378378a164d..62c482fd7ce 100644
--- a/packages/twenty-cli/CONTRIBUTING.md
+++ b/packages/twenty-cli/CONTRIBUTING.md
@@ -73,7 +73,7 @@ Changes must preserve these contracts:
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 preview; approval does not carry across dev revisions.
+ 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
diff --git a/packages/twenty-cli/docs/commands.md b/packages/twenty-cli/docs/commands.md
index c6b75119714..0c0a10d79b3 100644
--- a/packages/twenty-cli/docs/commands.md
+++ b/packages/twenty-cli/docs/commands.md
@@ -291,7 +291,7 @@ twenty app plan --path ./apps/billing --no-delete --json
JSON marks plans with `plan: true`. A plan is not a saved approval: remote changes can alter what a later apply does. A missing owned application registration returns `PLAN_UNAVAILABLE` (exit 1). Register the app with `twenty app apply --create`, then plan again.
-Entities missing from source are included as deletions by default. `--no-delete` passes `inferDeletionFromMissingEntities: false` to the preview. Human output lists every action, identifies object/field deletions that would remove stored data, and shows the opt-out hint. JSON includes action details and counts. Application-variable values, including previous values in updates, are redacted from all plan actions regardless of their `isSecret` setting. A plan exceeding 10,000 actions or the transport's 16 MiB response limit fails instead of displaying an incomplete preview.
+Entities missing from source are included as deletions by default. `--no-delete` passes `inferDeletionFromMissingEntities: false` to the preview. Human output lists every action, identifies object/field deletions that would remove stored data, and shows the opt-out hint. JSON includes action details and counts. Application-variable values, including previous values in updates, are redacted from all plan actions regardless of their `isSecret` setting. A plan exceeding 10,000 actions or the transport's 16 MiB response limit fails instead of displaying an incomplete plan.
## Apply an app
@@ -301,16 +301,16 @@ twenty app apply --create --json
twenty app apply --no-delete
```
-`app apply` builds the app once with the CLI pipeline and keeps that build's snapshot until it finishes, so the files it uploads are the ones it built. It then asks the workspace for a fresh preview, shows it, and applies it: it installs the development app if needed, uploads the snapshot files, synchronizes the manifest, and regenerates the app's typed API client. It needs the server's `APPLICATIONS` and `UPLOAD_FILE` permissions.
+`app apply` builds the app once with the CLI pipeline and keeps that build's snapshot until it finishes, so the files it uploads are the ones it built. It then asks the workspace for a fresh plan, shows it, and applies it: it installs the development app if needed, uploads the snapshot files, synchronizes the manifest, and regenerates the app's typed API client. It needs the server's `APPLICATIONS` and `UPLOAD_FILE` permissions.
-- **New apps.** An app without a registration needs `--create`, or a yes at the prompt in an interactive terminal. The CLI then registers the app (the server also requires `API_KEYS_AND_WEBHOOKS` for this), installs it, and previews it before uploading anything. Without approval it stops with `CREATE_REQUIRED` (exit 2). The registration's client secret is never requested.
-- **Deletions.** Entities missing from source are deleted by default, as in `app plan`; `--no-delete` keeps them and is sent to both the preview and the sync. Object and field deletions permanently delete stored data, so they need `--yes` or a yes at the prompt. Otherwise the command stops with `CONFIRMATION_REQUIRED` (exit 2) before changing anything. `--yes` never changes which entities are deleted.
+- **New apps.** An app without a registration needs `--create`, or a yes at the prompt in an interactive terminal. The CLI then registers the app (the server also requires `API_KEYS_AND_WEBHOOKS` for this), installs it, and plans its changes before uploading anything. Without approval it stops with `CREATE_REQUIRED` (exit 2). The registration's client secret is never requested.
+- **Deletions.** Entities missing from source are deleted by default, as in `app plan`; `--no-delete` keeps them and is sent to both the plan and the sync. Object and field deletions permanently delete stored data, so they need `--yes` or a yes at the prompt. Otherwise the command stops with `CONFIRMATION_REQUIRED` (exit 2) before changing anything. `--yes` never changes which entities are deleted.
- **Uploads.** File bytes go straight to the upload URLs the server returns, without the CLI's credentials. Each file is checked against the build's size and SHA-256 before anything is uploaded.
- **Pull baseline.** After an acknowledged sync, the CLI fetches the workspace ID and fresh application export, then atomically records `.twenty/cli/pull-base.json`. This baseline lets `app pull` distinguish workspace changes from local edits. It is bound to the normalized API URL, workspace UUID and app UUID. JSON reports `pullBase: "recorded"`, `"failed"` or `"unsupported"`; only a recorded base adds `pullBase` to `completedPhases`. Invalid exports or file-write errors preserve the prior base, warn with `PULL_BASE_NOT_RECORDED`, and allow client generation to continue. A server without the export API reports `"unsupported"` without a warning on every apply. The export is recorded as the server sent it; collections it lacks are read as empty by pull. Cancellation before the base is committed exits 130 with `outcome: "applied"` and `phase: "pullBase"`.
- **Typed client.** After the sync, the CLI fetches the app's GraphQL schema from the workspace and calls the app's own `twenty-client-sdk/generate` to regenerate the client in the app's own `node_modules/twenty-client-sdk` (`clientGeneration: "generated"`). It is skipped with a `CLIENT_NOT_GENERATED` warning when the app has no `node_modules/twenty-client-sdk` of its own, as in a hoisted workspace. A symlinked client package is followed and its target rewritten, so don't apply two apps that share one client package at the same time.
-- **Failures.** A failed apply reports `details.phase`, `details.completedPhases` and `details.outcome`: `not-started` when the failing step changed nothing, `partial` when some files were uploaded, `unknown` when a request was sent but its effect is not known, such as a failed or interrupted sync, and `applied` when the sync succeeded but baseline recording was cancelled or client generation failed. Earlier steps, like a new registration, stay done. There is no rollback and no automatic retry: run `twenty app plan` to see where the workspace stands, then apply again. After `applied`, the workspace has the new version but the client files may be incomplete: fix the problem, then run `twenty app apply` again, which repeats the preview, upload and sync before regenerating the client. Ctrl+C exits with 130 and reports the step it interrupted.
+- **Failures.** A failed apply reports `details.phase`, `details.completedPhases` and `details.outcome`: `not-started` when the failing step changed nothing, `partial` when some files were uploaded, `unknown` when a request was sent but its effect is not known, such as a failed or interrupted sync, and `applied` when the sync succeeded but baseline recording was cancelled or client generation failed. Earlier steps, like a new registration, stay done. There is no rollback and no automatic retry: run `twenty app plan` to see where the workspace stands, then apply again. After `applied`, the workspace has the new version but the client files may be incomplete: fix the problem, then run `twenty app apply` again, which repeats the plan, upload and sync before regenerating the client. Ctrl+C exits with 130 and reports the step it interrupted.
-Remote changes made between the preview and the sync can change what the sync does. Remote changes between the acknowledged sync and the export can also enter the saved baseline without appearing in local source; this is not an atomic server snapshot of the sync. Planning, a failed sync, or a sync with an unknown outcome never advances the baseline.
+Remote changes made between the plan and the sync can change what the sync does. Remote changes between the acknowledged sync and the export can also enter the saved baseline without appearing in local source; this is not an atomic server snapshot of the sync. Planning, a failed sync, or a sync with an unknown outcome never advances the baseline.
## Develop an app
@@ -344,10 +344,10 @@ edits settle, not an atomic checkout of files being edited concurrently.
Registration uses `--create` or a terminal confirmation. Deletion inference is
on by default, with `--no-delete` to keep missing entities. Object and field
deletions require a terminal confirmation or `--yes`. Every revision requests a
-fresh preview. An edit cancels a pending confirmation; approval for the
+fresh plan. An edit cancels a pending confirmation; approval for the
old revision cannot authorize the new one. A remote failure is reported with the
same phase/outcome details as apply and is retried only after a new source edit,
-with a new preview. Inspect `twenty app plan` when a request's outcome is unknown.
+with a new plan. Inspect `twenty app plan` when a request's outcome is unknown.
After an acknowledged sync, dev records the pull base and regenerates the app's
own typed client when its schema, generator package or generated files changed.
diff --git a/packages/twenty-cli/src/app/deployment/apply-app-build.ts b/packages/twenty-cli/src/app/deployment/apply-app-build.ts
index e66d279b7f6..594604e6c16 100644
--- a/packages/twenty-cli/src/app/deployment/apply-app-build.ts
+++ b/packages/twenty-cli/src/app/deployment/apply-app-build.ts
@@ -148,7 +148,7 @@ export const applyAppBuild = async ({
await runPhase('installation', () =>
installDevelopmentApp({ application, target, signal }),
);
- output.progress('Requesting a preview…');
+ output.progress('Computing metadata plan…');
return {
actions: await runPhase('preview', preview),
@@ -161,7 +161,7 @@ export const applyAppBuild = async ({
appPath,
});
- output.progress(`Requesting a fresh preview from ${target.apiUrl}…`);
+ output.progress(`Computing metadata plan on ${target.apiUrl}…`);
const { actions, isRegistrationCreated } = await previewOrBootstrap();
const summary = getAppPlanSummary(actions);
@@ -187,7 +187,7 @@ export const applyAppBuild = async ({
isApproved: isDeletionApproved,
question: `Apply ${summary.destructive} ${deletionLabel} stored data on ${target.apiUrl}?`,
code: 'CONFIRMATION_REQUIRED',
- message: `The preview includes ${summary.destructive} ${deletionLabel} stored data.`,
+ message: `The plan includes ${summary.destructive} ${deletionLabel} stored data.`,
hint: 'Review it with twenty app plan, then pass --yes to apply it, or --no-delete to keep entities missing from source.',
});
}
diff --git a/packages/twenty-cli/src/commands/app/__tests__/app-apply.spec.ts b/packages/twenty-cli/src/commands/app/__tests__/app-apply.spec.ts
index 4508e342f2f..861adb41902 100644
--- a/packages/twenty-cli/src/commands/app/__tests__/app-apply.spec.ts
+++ b/packages/twenty-cli/src/commands/app/__tests__/app-apply.spec.ts
@@ -1601,7 +1601,7 @@ describe('app apply', () => {
expect(refused.envelope.error).toMatchObject({
code: 'CONFIRMATION_REQUIRED',
message:
- 'The preview includes 1 object or field deletion that permanently deletes stored data.',
+ 'The plan includes 1 object or field deletion that permanently deletes stored data.',
hint: expect.stringContaining('--yes'),
details: { phase: 'confirmation', completedPhases: ['build', 'preview'] },
});
@@ -1833,10 +1833,11 @@ describe('app apply', () => {
expect(await readReleasedBuildId()).toBe('build-id');
});
- it('prints the preview on stderr and a summary on stdout', async () => {
+ it('prints the plan on stderr and a summary on stdout', async () => {
const { stdout, stderr, exitCode } = await run();
expect(exitCode).toBe(0);
+ expect(stderr).toContain(`Computing metadata plan on ${server.url}…`);
expect(stderr).toContain('Plan: 1 to add, 0 to change, 0 to destroy.');
expect(stderr).toContain('typed API client was not regenerated');
expect(stdout).toContain(`Applied Apply App to ${server.url}`);
diff --git a/packages/twenty-cli/src/commands/app/add/run-app-add-command.ts b/packages/twenty-cli/src/commands/app/add/run-app-add-command.ts
index 78f2446de69..4a685b322c2 100644
--- a/packages/twenty-cli/src/commands/app/add/run-app-add-command.ts
+++ b/packages/twenty-cli/src/commands/app/add/run-app-add-command.ts
@@ -60,7 +60,7 @@ export const runAppAddCommand: CommandRun = async (context) => {
]
: []),
'',
- 'Review the definition, then run twenty app build.',
+ 'Review with twenty app plan, then run twenty app apply.',
].join('\n'),
};
};
diff --git a/packages/twenty-cli/src/commands/app/dev/run-app-dev-command.ts b/packages/twenty-cli/src/commands/app/dev/run-app-dev-command.ts
index e228277683e..e6468976f62 100644
--- a/packages/twenty-cli/src/commands/app/dev/run-app-dev-command.ts
+++ b/packages/twenty-cli/src/commands/app/dev/run-app-dev-command.ts
@@ -64,7 +64,7 @@ export const runAppDevCommand: CommandRun<TargetCommandContext> = async (
await emit(
{
kind: 'build-start',
- message: `Building revision ${revision}…`,
+ message: 'Building app…',
revision,
},
signal,
@@ -154,7 +154,7 @@ export const runAppDevCommand: CommandRun<TargetCommandContext> = async (
await emit(
{
kind: 'sync-start',
- message: `Previewing revision ${revision}…`,
+ message: 'Planning changes…',
revision,
buildId: snapshot.build.buildId,
},
@@ -190,7 +190,7 @@ export const runAppDevCommand: CommandRun<TargetCommandContext> = async (
await emit(
{
kind: 'sync-superseded',
- message: 'Source changed; a fresh preview is queued.',
+ message: 'Source changed; a fresh plan is queued.',
revision,
details: failure.details,
},
@@ -206,7 +206,7 @@ export const runAppDevCommand: CommandRun<TargetCommandContext> = async (
await emit(
{
kind: 'sync-failure',
- message: `${failure.message} A new source edit will request a fresh preview.`,
+ message: `${failure.message} A new source edit will request a fresh plan.`,
revision,
error: {
code: failure.code,
@@ -279,7 +279,7 @@ export const runAppDevCommand: CommandRun<TargetCommandContext> = async (
message:
reason === 'unchanged'
? 'Build unchanged since the last acknowledged sync.'
- : 'Source changed during the build; rebuilding the latest revision.',
+ : 'Source changed during the build; rebuilding…',
revision,
reason,
},