The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
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.mdxindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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)) {