Skip to content

The open alternative to Salesforce, designed for AI.

Print export reasons in the pull report (#26288)

Weikoa417f4cb4047
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.mdx
index c0318342ceb..284345d7375 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
@@ -137,7 +137,9 @@ 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 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 `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.
+
+**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.
**The base file.** Pull records what it pulled in `.twenty/pull-base.json`, which is gitignored and per checkout. That file is what a later pull compares against to leave untouched the files whose entity did not change, and to delete the file of an entity that is gone from the workspace. A checkout without it simply writes everything and deletes nothing.
diff --git a/packages/twenty-sdk/src/cli/commands/dev/pull.ts b/packages/twenty-sdk/src/cli/commands/dev/pull.ts
index 4badb48578f..8a64f88fc48 100644
--- a/packages/twenty-sdk/src/cli/commands/dev/pull.ts
+++ b/packages/twenty-sdk/src/cli/commands/dev/pull.ts
@@ -51,6 +51,8 @@ export class AppPullCommand {
unreadableRelativePaths: result.data.unreadableRelativePaths,
compiledTranslationEntryCountByLocale:
result.data.compiledTranslationEntryCountByLocale,
+ entityLabelByUniversalIdentifier:
+ result.data.entityLabelByUniversalIdentifier,
verbose: options.verbose,
});
diff --git a/packages/twenty-sdk/src/cli/operations/pull.ts b/packages/twenty-sdk/src/cli/operations/pull.ts
index a75038bd906..39cde12f925 100644
--- a/packages/twenty-sdk/src/cli/operations/pull.ts
+++ b/packages/twenty-sdk/src/cli/operations/pull.ts
@@ -10,6 +10,7 @@ import {
import { pathExists } from '@/cli/utilities/file/fs-utils';
import { type ApplicationExportCoverageEntry } from '@/cli/utilities/pull/application-export-type';
import { applyPullWrites } from '@/cli/utilities/pull/apply-pull-writes';
+import { buildManifestEntityLabelByUniversalIdentifier } from '@/cli/utilities/pull/build-manifest-entity-label-by-universal-identifier';
import { type SkippedPullEntity } from '@/cli/utilities/pull/build-pull-entities';
import {
planPullWrites,
@@ -45,6 +46,7 @@ export type AppPullResult = {
coverage: ApplicationExportCoverageEntry[];
unreadableRelativePaths: string[];
compiledTranslationEntryCountByLocale: Record<string, number>;
+ entityLabelByUniversalIdentifier: Record<string, string>;
hadBase: boolean;
isSdkResolvable: boolean;
};
@@ -229,6 +231,8 @@ const innerAppPull = async (
.map((scannedFile) => scannedFile.relativePath),
compiledTranslationEntryCountByLocale:
translationPlan.compiledEntryCountByLocale,
+ entityLabelByUniversalIdentifier:
+ buildManifestEntityLabelByUniversalIdentifier(manifest),
hadBase: isDefined(baseManifest),
isSdkResolvable: isSdkResolvable(appPath),
},
diff --git a/packages/twenty-sdk/src/cli/utilities/pull/__tests__/build-manifest-entity-label-by-universal-identifier.spec.ts b/packages/twenty-sdk/src/cli/utilities/pull/__tests__/build-manifest-entity-label-by-universal-identifier.spec.ts
new file mode 100644
index 00000000000..d7c9183f791
--- /dev/null
+++ b/packages/twenty-sdk/src/cli/utilities/pull/__tests__/build-manifest-entity-label-by-universal-identifier.spec.ts
@@ -0,0 +1,85 @@
+import { buildManifestEntityLabelByUniversalIdentifier } from '@/cli/utilities/pull/build-manifest-entity-label-by-universal-identifier';
+import { describe, expect, it } from 'vitest';
+
+describe('buildManifestEntityLabelByUniversalIdentifier', () => {
+ it('should qualify a nested entity with the labels of its parents', () => {
+ expect(
+ buildManifestEntityLabelByUniversalIdentifier({
+ objects: [
+ {
+ universalIdentifier: 'ticket-identifier',
+ nameSingular: 'ticket',
+ namePlural: 'tickets',
+ fields: [
+ { universalIdentifier: 'labels-identifier', name: 'labels' },
+ ],
+ },
+ ],
+ pageLayouts: [
+ {
+ universalIdentifier: 'layout-identifier',
+ name: 'Dashboard',
+ tabs: [
+ {
+ universalIdentifier: 'tab-identifier',
+ title: 'Overview',
+ widgets: [
+ {
+ universalIdentifier: 'widget-identifier',
+ title: 'Runbook',
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ roles: [{ universalIdentifier: 'role-identifier', label: 'Recruiter' }],
+ }),
+ ).toEqual({
+ 'ticket-identifier': 'ticket',
+ 'labels-identifier': 'ticket.labels',
+ 'layout-identifier': 'Dashboard',
+ 'tab-identifier': 'Dashboard.Overview',
+ 'widget-identifier': 'Dashboard.Overview.Runbook',
+ 'role-identifier': 'Recruiter',
+ });
+ });
+
+ it('should leave out an entity that carries no label of its own', () => {
+ expect(
+ buildManifestEntityLabelByUniversalIdentifier({
+ application: {
+ universalIdentifier: 'application-identifier',
+ displayName: 'Custom',
+ },
+ views: [
+ {
+ universalIdentifier: 'view-identifier',
+ name: 'Open tickets',
+ fields: [
+ {
+ universalIdentifier: 'view-field-identifier',
+ fieldMetadataUniversalIdentifier: 'labels-identifier',
+ },
+ ],
+ },
+ ],
+ }),
+ ).toEqual({ 'view-identifier': 'Open tickets' });
+ });
+
+ it('should never register the labelled entries of a JSON value', () => {
+ expect(
+ buildManifestEntityLabelByUniversalIdentifier({
+ fields: [
+ {
+ universalIdentifier: 'priority-identifier',
+ name: 'priority',
+ options: [{ id: 'option-id', label: 'High', value: 'HIGH' }],
+ defaultValue: { name: 'ignored' },
+ },
+ ],
+ }),
+ ).toEqual({ 'priority-identifier': 'priority' });
+ });
+});
diff --git a/packages/twenty-sdk/src/cli/utilities/pull/__tests__/format-pull-report.spec.ts b/packages/twenty-sdk/src/cli/utilities/pull/__tests__/format-pull-report.spec.ts
index 8792f59bcf9..af72687ed4d 100644
--- a/packages/twenty-sdk/src/cli/utilities/pull/__tests__/format-pull-report.spec.ts
+++ b/packages/twenty-sdk/src/cli/utilities/pull/__tests__/format-pull-report.spec.ts
@@ -108,6 +108,91 @@ describe('formatPullReport', () => {
expect(verboseReport).toContain('…and 5 more');
});
+ it('should print the reason next to each count and split a kind by reason', () => {
+ const report = buildReport({
+ coverage: buildCoverage([
+ {
+ metadataName: 'roleTarget',
+ status: 'EXCLUDED',
+ reason: 'member or API key role assignment',
+ },
+ {
+ metadataName: 'roleTarget',
+ status: 'EXCLUDED',
+ reason: 'member or API key role assignment',
+ },
+ {
+ metadataName: 'navigationMenuItem',
+ status: 'EXCLUDED',
+ reason: 'personal navigation item',
+ },
+ {
+ metadataName: 'navigationMenuItem',
+ status: 'EXCLUDED',
+ reason: 'navigation item pinned to a record',
+ },
+ ]),
+ });
+
+ expect(report).toMatch(
+ /roleTarget\s+2\s+member or API key role assignment/,
+ );
+ expect(report).toMatch(
+ /navigationMenuItem\s+1\s+navigation item pinned to a record/,
+ );
+ expect(report).toMatch(/navigationMenuItem\s+1\s+personal navigation item/);
+ });
+
+ it('should name the exported rows written without their workspace-local state', () => {
+ const report = buildReport({
+ coverage: buildCoverage([
+ { metadataName: 'objectMetadata', status: 'EXPORTED' },
+ {
+ metadataName: 'objectMetadata',
+ universalIdentifier: 'survey-result-identifier',
+ status: 'EXPORTED',
+ reason: 'deactivated in this workspace, exported active',
+ },
+ {
+ metadataName: 'fieldMetadata',
+ universalIdentifier: 'unlabelled-identifier',
+ status: 'EXPORTED',
+ reason: 'workspace overrides not exported',
+ },
+ ]),
+ entityLabelByUniversalIdentifier: {
+ 'survey-result-identifier': 'surveyResult',
+ },
+ });
+
+ expect(report).toContain(
+ 'Written without their workspace-local state (2 row(s)):',
+ );
+ expect(report).toContain(
+ 'objectMetadata surveyResult: deactivated in this workspace, exported active',
+ );
+ expect(report).toContain(
+ 'fieldMetadata unlabelled-identifier: workspace overrides not exported',
+ );
+ expect(report).not.toContain('identifier-0');
+ });
+
+ it('should cap the rows written without their workspace-local state unless verbose', () => {
+ const coverage = buildCoverage(
+ Array.from({ length: 25 }, () => ({
+ metadataName: 'fieldMetadata',
+ status: 'EXPORTED' as const,
+ reason: 'workspace overrides not exported',
+ })),
+ );
+
+ const report = buildReport({ coverage });
+
+ expect(report).toContain('…and 5 more, listed with --verbose');
+ expect(report).not.toContain('identifier-9');
+ expect(buildReport({ coverage, verbose: true })).toContain('identifier-9');
+ });
+
it('should name the entities the writer refused to write', () => {
const report = buildReport({
skipped: [
diff --git a/packages/twenty-sdk/src/cli/utilities/pull/build-manifest-entity-label-by-universal-identifier.ts b/packages/twenty-sdk/src/cli/utilities/pull/build-manifest-entity-label-by-universal-identifier.ts
new file mode 100644
index 00000000000..e50ba8673a2
--- /dev/null
+++ b/packages/twenty-sdk/src/cli/utilities/pull/build-manifest-entity-label-by-universal-identifier.ts
@@ -0,0 +1,46 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { isDefined, isPlainObject } from 'twenty-shared/utils';
+
+const LABEL_KEYS = ['nameSingular', 'name', 'label', 'title'] as const;
+
+export const buildManifestEntityLabelByUniversalIdentifier = (
+ manifest: Record<string, unknown>,
+): Record<string, string> => {
+ const labelByUniversalIdentifier: Record<string, string> = {};
+
+ const visit = (value: unknown, parentLabel: string | undefined): void => {
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ visit(item, parentLabel);
+ }
+
+ return;
+ }
+
+ if (!isPlainObject(value)) {
+ return;
+ }
+
+ const ownLabel = LABEL_KEYS.map((key) => value[key]).find(isNonEmptyString);
+ const label =
+ isDefined(ownLabel) && isDefined(parentLabel)
+ ? `${parentLabel}.${ownLabel}`
+ : (ownLabel ?? parentLabel);
+
+ if (
+ isDefined(ownLabel) &&
+ isDefined(label) &&
+ isNonEmptyString(value.universalIdentifier)
+ ) {
+ labelByUniversalIdentifier[value.universalIdentifier] = label;
+ }
+
+ for (const child of Object.values(value)) {
+ visit(child, label);
+ }
+ };
+
+ visit(manifest, undefined);
+
+ return labelByUniversalIdentifier;
+};
diff --git a/packages/twenty-sdk/src/cli/utilities/pull/format-pull-report.ts b/packages/twenty-sdk/src/cli/utilities/pull/format-pull-report.ts
index cbe3e9f95b5..4f83fc367e2 100644
--- a/packages/twenty-sdk/src/cli/utilities/pull/format-pull-report.ts
+++ b/packages/twenty-sdk/src/cli/utilities/pull/format-pull-report.ts
@@ -4,6 +4,7 @@ import {
type PullDeletion,
type PullWrite,
} from '@/cli/utilities/pull/plan-pull-writes';
+import { isDefined } from 'twenty-shared/utils';
const MAX_LISTED_IDENTIFIERS = 20;
@@ -40,21 +41,34 @@ const formatFileGroup = ({
.sort()
.map((relativePath) => ` ${title.padEnd(13)}${relativePath}`);
-const groupIdentifiersByMetadataName = (
+type CoverageGroup = {
+ metadataName: string;
+ reason: string | null;
+ identifiers: string[];
+};
+
+const groupCoverageByMetadataNameAndReason = (
coverage: ApplicationExportCoverageEntry[],
-): Map<string, string[]> => {
- const identifiersByMetadataName = new Map<string, string[]>();
+): CoverageGroup[] => {
+ const groupByKey = new Map<string, CoverageGroup>();
for (const entry of coverage) {
- const identifiers = identifiersByMetadataName.get(entry.metadataName) ?? [];
-
- identifiersByMetadataName.set(entry.metadataName, [
- ...identifiers,
- entry.universalIdentifier,
- ]);
+ const key = JSON.stringify([entry.metadataName, entry.reason]);
+ const group = groupByKey.get(key) ?? {
+ metadataName: entry.metadataName,
+ reason: entry.reason,
+ identifiers: [],
+ };
+
+ group.identifiers.push(entry.universalIdentifier);
+ groupByKey.set(key, group);
}
- return identifiersByMetadataName;
+ return [...groupByKey.values()].sort(
+ (left, right) =>
+ left.metadataName.localeCompare(right.metadataName) ||
+ (left.reason ?? '').localeCompare(right.reason ?? ''),
+ );
};
export const formatPullReport = ({
@@ -66,6 +80,7 @@ export const formatPullReport = ({
localOnlyRelativePaths,
unreadableRelativePaths = [],
compiledTranslationEntryCountByLocale = {},
+ entityLabelByUniversalIdentifier = {},
verbose = false,
}: {
writes: PullWrite[];
@@ -76,6 +91,7 @@ export const formatPullReport = ({
localOnlyRelativePaths: string[];
unreadableRelativePaths?: string[];
compiledTranslationEntryCountByLocale?: Record<string, number>;
+ entityLabelByUniversalIdentifier?: Record<string, string>;
verbose?: boolean;
}): string => {
const lines: string[] = [
@@ -131,6 +147,37 @@ export const formatPullReport = ({
);
}
+ const writtenWithoutLocalState = coverage
+ .filter((entry) => entry.status === 'EXPORTED' && isDefined(entry.reason))
+ .map(
+ (entry) =>
+ ` ${entry.metadataName} ${
+ entityLabelByUniversalIdentifier[entry.universalIdentifier] ??
+ entry.universalIdentifier
+ }: ${entry.reason}`,
+ )
+ .sort();
+
+ if (writtenWithoutLocalState.length > 0) {
+ const listedWrittenWithoutLocalState = verbose
+ ? writtenWithoutLocalState
+ : writtenWithoutLocalState.slice(0, MAX_LISTED_IDENTIFIERS);
+
+ lines.push(
+ '',
+ `Written without their workspace-local state (${writtenWithoutLocalState.length} row(s)):`,
+ ...listedWrittenWithoutLocalState,
+ );
+
+ if (
+ writtenWithoutLocalState.length > listedWrittenWithoutLocalState.length
+ ) {
+ lines.push(
+ ` …and ${writtenWithoutLocalState.length - listedWrittenWithoutLocalState.length} more, listed with --verbose`,
+ );
+ }
+ }
+
for (const section of COVERAGE_SECTIONS) {
const sectionEntries = coverage.filter(
(entry) => entry.status === section.status,
@@ -142,13 +189,14 @@ export const formatPullReport = ({
lines.push('', `${section.title} (${sectionEntries.length} row(s)):`);
- const identifiersByMetadataName =
- groupIdentifiersByMetadataName(sectionEntries);
-
- for (const [metadataName, identifiers] of [
- ...identifiersByMetadataName.entries(),
- ].sort(([left], [right]) => left.localeCompare(right))) {
- lines.push(` ${metadataName.padEnd(34)}${identifiers.length}`);
+ for (const {
+ metadataName,
+ reason,
+ identifiers,
+ } of groupCoverageByMetadataNameAndReason(sectionEntries)) {
+ lines.push(
+ ` ${metadataName.padEnd(34)}${String(identifiers.length).padEnd(6)}${reason ?? ''}`.trimEnd(),
+ );
if (verbose) {
for (const identifier of identifiers.slice(0, MAX_LISTED_IDENTIFIERS)) {