The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
feat(cli): ship a yarn.lock with the app template (#27523)
Weiko69b2e5fc2042
diff --git a/packages/twenty-cli/CONTRIBUTING.md b/packages/twenty-cli/CONTRIBUTING.mdindex 42dc0310a0f..fda3d5ed2f6 100644--- a/packages/twenty-cli/CONTRIBUTING.md+++ b/packages/twenty-cli/CONTRIBUTING.md@@ -127,12 +127,23 @@ or templates are missing, when `dist` was built for another version, when one ofits CLI runs fails or times out, or when `app init` would pin versions that arenot on npm. An unreachable registry is reported separately from a missingversion. The check does not read tags: it confirms that the pinned versions are-published, and tagging the SDK release commit remains a release step. Its tests-run with `twenty-cli:test:package`. To run the check itself before tagging:+published, and tagging the SDK release commit remains a release step.++`prepublish` then runs `scripts/generate-template-lock.mjs`. It resolves the app+template's dependencies with the repository's Yarn against the public registry,+under a 3-day minimum release age that exempts the pinned Twenty packages, and+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 scripts run with `twenty-cli:test:package`. To run the scripts+before tagging:```bashyarn nx build twenty-clinode packages/twenty-cli/scripts/check-publish.mjs+node packages/twenty-cli/scripts/generate-template-lock.mjs```## App integration testsdiff --git a/packages/twenty-cli/docs/commands.md b/packages/twenty-cli/docs/commands.mdindex 2b3d5d8036c..09bb6f54b76 100644--- a/packages/twenty-cli/docs/commands.md+++ b/packages/twenty-cli/docs/commands.md@@ -186,7 +186,7 @@ twenty app init my-apptwenty app init billing --path ./apps/billing --display-name Billing --json```-`app init` creates a new app from the template bundled with the CLI, with fresh universal identifiers and `twenty-client-sdk`, `twenty-sdk` and `twenty-ui` pinned to the exact version the CLI was built with. It needs no installed SDK, saved remote or network access, and it only writes files: it does not install dependencies, create a Git repository, start a server, sign in or sync anything. The next steps it prints, and returns as `data.nextSteps` in JSON, cover the rest, and name the remote when you pass `--remote`.+`app init` creates a new app from the template bundled with the CLI, with fresh universal identifiers and `twenty-client-sdk`, `twenty-sdk` and `twenty-ui` pinned to the exact version the CLI was built with. It needs no installed SDK, saved remote or network access, and it only writes files: it does not install dependencies, create a Git repository, start a server, sign in or sync anything. A published CLI also writes a `yarn.lock`, so the first `yarn install` uses exact, integrity-checked versions. The next steps it prints, and returns as `data.nextSteps` in JSON, cover the rest, and name the remote when you pass `--remote`.The name must be a valid npm package name, otherwise the command fails with `INVALID_APP_NAME` (exit 2). The app is created in `./<name>` unless `--path` says otherwise; `--display-name` and `--description` set what Twenty shows. The target must not exist yet or be an empty directory; anything else fails with `APP_PATH_UNAVAILABLE` (exit 6) and nothing is written. The template is rendered in a hidden sibling directory and moved into place only after every placeholder was filled, so a failure or Ctrl+C does not leave a half-created app behind. An existing empty directory is filled with create-only writes, so a file that appears there meanwhile is never overwritten.diff --git a/packages/twenty-cli/package.json b/packages/twenty-cli/package.jsonindex ec5788e79ef..b5b9683baca 100644--- a/packages/twenty-cli/package.json+++ b/packages/twenty-cli/package.json@@ -21,7 +21,7 @@],"scripts": {"build": "npx rimraf dist && npx vite build",- "prepublish": "node scripts/check-publish.mjs"+ "prepublish": "node scripts/check-publish.mjs && node scripts/generate-template-lock.mjs"},"engines": {"node": "^24.5.0"diff --git a/packages/twenty-cli/project.json b/packages/twenty-cli/project.jsonindex 5a602bd378b..b3d45fc8c4b 100644--- a/packages/twenty-cli/project.json+++ b/packages/twenty-cli/project.json@@ -25,7 +25,7 @@"dependsOn": ["build"],"cache": false,"options": {- "command": "node --test packages/twenty-cli/scripts/test-check-publish.mjs packages/twenty-cli/scripts/test-package.mjs"+ "command": "node --test packages/twenty-cli/scripts/test-check-publish.mjs packages/twenty-cli/scripts/test-template-lock.mjs packages/twenty-cli/scripts/test-package.mjs"}},"test": {diff --git a/packages/twenty-cli/scripts/generate-template-lock.mjs b/packages/twenty-cli/scripts/generate-template-lock.mjsnew file mode 100644index 00000000000..6f97c0aca7b--- /dev/null+++ b/packages/twenty-cli/scripts/generate-template-lock.mjs@@ -0,0 +1,21 @@+import { fileURLToPath } from 'node:url';++import { generateTemplateLock, TemplateLockError } from './template-lock.mjs';++try {+ const { version, firstPartyPackages, resolutionCount } =+ await generateTemplateLock({+ packageDirectory: fileURLToPath(new URL('..', import.meta.url)),+ });++ console.log(+ `Wrote dist/app-template/yarn.lock with ${resolutionCount} resolutions, pinning ${firstPartyPackages.map((name) => `${name}@${version}`).join(', ')}`,+ );+} catch (error) {+ if (!(error instanceof TemplateLockError)) {+ throw error;+ }++ console.error(`Template lockfile failed: ${error.message}`);+ process.exitCode = 1;+}diff --git a/packages/twenty-cli/scripts/template-lock.mjs b/packages/twenty-cli/scripts/template-lock.mjsnew file mode 100644index 00000000000..fb0709492fa--- /dev/null+++ b/packages/twenty-cli/scripts/template-lock.mjs@@ -0,0 +1,207 @@+import { execFileSync } from 'node:child_process';+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { basename, join } from 'node:path';++export const PUBLIC_REGISTRY = 'https://registry.npmjs.org';++const RELEASE_MINIMAL_AGE_GATE = '3d';+const PIN_PLACEHOLDER = 'TO-BE-GENERATED';+const BUILD_HINT = 'Build it first with: yarn nx build twenty-cli';++export class TemplateLockError extends Error {}++const fail = (message) => {+ throw new TemplateLockError(message);+};++const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));++export const buildTemplateManifest = ({ templateManifest, version }) => {+ const firstPartyPackages = Object.entries(+ templateManifest.devDependencies ?? {},+ )+ .filter(([, pin]) => pin === PIN_PLACEHOLDER)+ .map(([name]) => name);++ if (firstPartyPackages.length === 0) {+ fail('The app template does not pin any first-party package.');+ }++ return {+ manifest: {+ ...templateManifest,+ devDependencies: {+ ...templateManifest.devDependencies,+ ...Object.fromEntries(+ firstPartyPackages.map((name) => [name, version]),+ ),+ },+ },+ firstPartyPackages,+ };+};++export const buildYarnrc = ({ registry, version, firstPartyPackages }) => {+ const { protocol, hostname } = new URL(registry);++ return [+ 'nodeLinker: node-modules',+ 'enableTelemetry: false',+ 'enableScripts: false',+ `npmRegistryServer: "${registry}"`,+ ...(protocol === 'http:'+ ? ['unsafeHttpWhitelist:', ` - ${hostname}`]+ : []),+ `npmMinimalAgeGate: ${RELEASE_MINIMAL_AGE_GATE}`,+ 'npmPreapprovedPackages:',+ ...firstPartyPackages.map((name) => ` - "${name}@${version}"`),+ '',+ ].join('\n');+};++export const resolveYarnBinary = async ({+ repositoryDirectory,+ packageManager,+}) => {+ const yarnrc = await readFile(+ join(repositoryDirectory, '.yarnrc.yml'),+ 'utf8',+ );+ const yarnPath = /^yarnPath:\s*(.+)$/m.exec(yarnrc)?.[1]?.trim();++ if (yarnPath === undefined) {+ fail('The repository .yarnrc.yml has no yarnPath.');+ }++ const repositoryYarnVersion = /yarn-(.+)\.cjs$/.exec(basename(yarnPath))?.[1];+ const templateYarnVersion = packageManager?.replace(/^yarn@/, '');++ if (repositoryYarnVersion !== templateYarnVersion) {+ fail(+ `The app template pins yarn@${templateYarnVersion}, but the repository runs yarn ${repositoryYarnVersion}. Align them before generating the lockfile.`,+ );+ }++ return join(repositoryDirectory, yarnPath);+};++export const assertResolvedWithIntegrity = ({+ lockfile,+ packageName,+ version,+}) => {+ const resolution = `resolution: "${packageName}@npm:${version}"`;+ const resolutionIndex = lockfile.indexOf(resolution);++ if (resolutionIndex === -1) {+ fail(+ `${packageName}@${version} is missing from the generated lockfile. Is it published?`,+ );+ }++ const entryEnd = lockfile.indexOf('\n\n', resolutionIndex);+ const entry = lockfile.slice(+ resolutionIndex,+ entryEnd === -1 ? undefined : entryEnd,+ );++ if (!entry.includes('checksum:')) {+ fail(`${packageName}@${version} resolved without an integrity checksum.`);+ }+};++export const assertNoRegistryPinning = (lockfile) => {+ if (lockfile.includes('__archiveUrl')) {+ fail(+ 'The generated lockfile pins entries to a registry host. Generate it against the public registry.',+ );+ }+};++const installWithYarn = async ({ yarnBinary, workingDirectory }) => {+ const environment = Object.fromEntries(+ Object.entries(process.env).filter(([name]) => !name.startsWith('YARN_')),+ );++ execFileSync(+ process.execPath,+ [yarnBinary, 'install', '--mode=update-lockfile'],+ { cwd: workingDirectory, env: environment, stdio: 'inherit' },+ );+};++export const generateTemplateLock = async ({+ packageDirectory,+ registry = PUBLIC_REGISTRY,+ install = installWithYarn,+}) => {+ const outputDirectory = join(packageDirectory, 'dist/app-template');+ const outputDirectoryStatus = await stat(outputDirectory).catch(+ () => undefined,+ );++ if (outputDirectoryStatus?.isDirectory() !== true) {+ fail(`dist/app-template is missing. ${BUILD_HINT}`);+ }++ const templateManifest = await readJson(+ join(packageDirectory, 'app-template/package.json'),+ );+ const { version } = await readJson(+ join(packageDirectory, '../twenty-sdk/package.json'),+ );+ const { manifest, firstPartyPackages } = buildTemplateManifest({+ templateManifest,+ version,+ });+ const yarnBinary = await resolveYarnBinary({+ repositoryDirectory: join(packageDirectory, '../..'),+ packageManager: templateManifest.packageManager,+ });+ const workingDirectory = await mkdtemp(+ join(tmpdir(), 'twenty-template-lock-'),+ );++ try {+ await writeFile(+ join(workingDirectory, 'package.json'),+ `${JSON.stringify(manifest, null, 2)}\n`,+ );+ await writeFile(+ join(workingDirectory, '.yarnrc.yml'),+ buildYarnrc({ registry, version, firstPartyPackages }),+ );++ try {+ await install({ yarnBinary, workingDirectory });+ } catch {+ fail(+ `Yarn could not resolve the app template with ${firstPartyPackages.join(', ')} at ${version}. See the Yarn output above.`,+ );+ }++ const lockfile = await readFile(+ join(workingDirectory, 'yarn.lock'),+ 'utf8',+ );++ for (const packageName of firstPartyPackages) {+ assertResolvedWithIntegrity({ lockfile, packageName, version });+ }++ if (registry === PUBLIC_REGISTRY) {+ assertNoRegistryPinning(lockfile);+ }++ await writeFile(join(outputDirectory, 'yarn.lock'), lockfile);++ return {+ version,+ firstPartyPackages,+ resolutionCount: lockfile.match(/^ {2}resolution:/gm)?.length ?? 0,+ };+ } finally {+ await rm(workingDirectory, { recursive: true, force: true });+ }+};diff --git a/packages/twenty-cli/scripts/test-template-lock.mjs b/packages/twenty-cli/scripts/test-template-lock.mjsnew file mode 100644index 00000000000..bfcd93a70de--- /dev/null+++ b/packages/twenty-cli/scripts/test-template-lock.mjs@@ -0,0 +1,240 @@+import { strict as assert } from 'node:assert';+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { test } from 'node:test';++import {+ buildTemplateManifest,+ buildYarnrc,+ generateTemplateLock,+ PUBLIC_REGISTRY,+ TemplateLockError,+} from './template-lock.mjs';++const VERSION = '2.45.0';+const FIRST_PARTY_PACKAGES = ['twenty-client-sdk', 'twenty-sdk', 'twenty-ui'];+const TEMPLATE_MANIFEST = {+ name: 'TO-BE-GENERATED',+ packageManager: '[email protected]',+ devDependencies: {+ typescript: '^5.9.3',+ ...Object.fromEntries(+ FIRST_PARTY_PACKAGES.map((name) => [name, 'TO-BE-GENERATED']),+ ),+ },+};++const lockfileEntry = (name, { checksum = true } = {}) =>+ [+ `"${name}@npm:${VERSION}":`,+ ` version: ${VERSION}`,+ ` resolution: "${name}@npm:${VERSION}"`,+ ...(checksum ? [' checksum: 10c0/abc'] : []),+ ' languageName: node',+ ' linkType: hard',+ ].join('\n');++const createRepository = async ({+ yarnVersion = '4.13.0',+ hasBuild = true,+} = {}) => {+ const root = await mkdtemp(join(tmpdir(), 'twenty-template-lock-test-'));+ const packageDirectory = join(root, 'packages/twenty-cli');++ await mkdir(join(packageDirectory, 'app-template'), { recursive: true });+ await mkdir(join(root, 'packages/twenty-sdk'), { recursive: true });+ await writeFile(+ join(root, '.yarnrc.yml'),+ `yarnPath: .yarn/releases/yarn-${yarnVersion}.cjs\n`,+ );+ await writeFile(+ join(packageDirectory, 'app-template/package.json'),+ JSON.stringify(TEMPLATE_MANIFEST),+ );+ await writeFile(+ join(root, 'packages/twenty-sdk/package.json'),+ JSON.stringify({ name: 'twenty-sdk', version: VERSION }),+ );++ if (hasBuild) {+ await mkdir(join(packageDirectory, 'dist/app-template'), {+ recursive: true,+ });+ }++ return { root, packageDirectory };+};++const writeLockfile =+ (content) =>+ ({ workingDirectory }) =>+ writeFile(join(workingDirectory, 'yarn.lock'), content);++const testWithRepository = (name, options, run) =>+ test(name, async () => {+ const repository = await createRepository(options);++ try {+ await run(repository);+ } finally {+ await rm(repository.root, { recursive: true, force: true });+ }+ });++const assertFailure = (promise, pattern) =>+ assert.rejects(promise, (error) => {+ assert.ok(error instanceof TemplateLockError, error);+ assert.match(error.message, pattern);++ return true;+ });++await test('pins only the first-party placeholders of the app template', () => {+ const { manifest, firstPartyPackages } = buildTemplateManifest({+ templateManifest: TEMPLATE_MANIFEST,+ version: VERSION,+ });++ assert.deepEqual(firstPartyPackages, FIRST_PARTY_PACKAGES);+ assert.equal(manifest.name, 'TO-BE-GENERATED');+ assert.deepEqual(manifest.devDependencies, {+ typescript: '^5.9.3',+ 'twenty-client-sdk': VERSION,+ 'twenty-sdk': VERSION,+ 'twenty-ui': VERSION,+ });+});++await test('resolves under an age gate that preapproves only the pinned packages', () => {+ const yarnrc = buildYarnrc({+ registry: PUBLIC_REGISTRY,+ version: VERSION,+ firstPartyPackages: FIRST_PARTY_PACKAGES,+ });++ assert.match(yarnrc, /^npmMinimalAgeGate: 3d$/m);+ assert.match(yarnrc, /^enableScripts: false$/m);+ assert.match(yarnrc, /^ {2}- "twenty-sdk@2\.45\.0"$/m);+ assert.doesNotMatch(yarnrc, /unsafeHttpWhitelist/);+ assert.match(+ buildYarnrc({+ registry: 'http://127.0.0.1:4873',+ version: VERSION,+ firstPartyPackages: FIRST_PARTY_PACKAGES,+ }),+ /^unsafeHttpWhitelist:\n {2}- 127\.0\.0\.1$/m,+ );+});++await testWithRepository(+ 'writes the generated lockfile into the built template',+ {},+ async ({ packageDirectory }) => {+ const lockfile = `${FIRST_PARTY_PACKAGES.map((name) => lockfileEntry(name)).join('\n\n')}\n`;++ assert.deepEqual(+ await generateTemplateLock({+ packageDirectory,+ install: writeLockfile(lockfile),+ }),+ {+ version: VERSION,+ firstPartyPackages: FIRST_PARTY_PACKAGES,+ resolutionCount: 3,+ },+ );+ assert.equal(+ await readFile(+ join(packageDirectory, 'dist/app-template/yarn.lock'),+ 'utf8',+ ),+ lockfile,+ );+ },+);++await testWithRepository(+ 'refuses a pinned package that did not resolve with a checksum',+ {},+ async ({ packageDirectory }) => {+ await assertFailure(+ generateTemplateLock({+ packageDirectory,+ install: writeLockfile(lockfileEntry('twenty-sdk')),+ }),+ /^twenty-client-sdk@2\.45\.0 is missing from the generated lockfile/,+ );+ await assertFailure(+ generateTemplateLock({+ packageDirectory,+ install: writeLockfile(+ FIRST_PARTY_PACKAGES.map((name) =>+ lockfileEntry(name, { checksum: name !== 'twenty-ui' }),+ ).join('\n\n'),+ ),+ }),+ /^twenty-ui@2\.45\.0 resolved without an integrity checksum/,+ );+ },+);++await testWithRepository(+ 'refuses entries pinned to a registry host',+ {},+ async ({ packageDirectory }) => {+ await assertFailure(+ generateTemplateLock({+ packageDirectory,+ install: writeLockfile(+ `${FIRST_PARTY_PACKAGES.map((name) => lockfileEntry(name)).join('\n\n')}\n __archiveUrl: https://mirror.example.com\n`,+ ),+ }),+ /pins entries to a registry host/,+ );+ },+);++await testWithRepository(+ 'reports a failed resolution',+ {},+ async ({ packageDirectory }) => {+ await assertFailure(+ generateTemplateLock({+ packageDirectory,+ install: () => {+ throw new Error('YN0082: No candidates found');+ },+ }),+ /^Yarn could not resolve the app template with twenty-client-sdk, twenty-sdk, twenty-ui at 2\.45\.0/,+ );+ },+);++await testWithRepository(+ 'refuses a template whose Yarn differs from the repository',+ { yarnVersion: '4.12.0' },+ async ({ packageDirectory }) => {+ await assertFailure(+ generateTemplateLock({+ packageDirectory,+ install: writeLockfile(''),+ }),+ /pins yarn@4\.13\.0, but the repository runs yarn 4\.12\.0/,+ );+ },+);++await testWithRepository(+ 'needs a built template',+ { hasBuild: false },+ async ({ packageDirectory }) => {+ await assertFailure(+ generateTemplateLock({+ packageDirectory,+ install: writeLockfile(''),+ }),+ /^dist\/app-template is missing/,+ );+ },+);diff --git a/packages/twenty-cli/src/app/create-app-project.ts b/packages/twenty-cli/src/app/create-app-project.tsindex bce947beeff..fa7be77f1bd 100644--- a/packages/twenty-cli/src/app/create-app-project.ts+++ b/packages/twenty-cli/src/app/create-app-project.ts@@ -21,6 +21,7 @@ import { EXIT_CODE } from '@/output/constants/exit-code.constant';import { hasErrorCode } from '@/utils/has-error-code';const TEMPLATE_PLACEHOLDER = 'TO-BE-GENERATED';+const LOCKFILE_REWRITTEN_BY_INSTALL = 'yarn.lock';const createAppPathUnavailableError = ({appDirectory,@@ -78,12 +79,14 @@ const findUnrenderedFiles = async (directory: string) => {for (const entry of entries) {const filePath = join(entry.parentPath, entry.name);+ const relativePath = relative(directory, filePath);if (entry.isFile() &&+ relativePath !== LOCKFILE_REWRITTEN_BY_INSTALL &&(await readFile(filePath, 'utf8')).includes(TEMPLATE_PLACEHOLDER)) {- unrenderedFiles.push(relative(directory, filePath));+ unrenderedFiles.push(relativePath);}}diff --git a/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts b/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.tsindex 38f1ded9c03..aaf4fa4dc7f 100644--- a/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts+++ b/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts@@ -405,4 +405,21 @@ describe('app init', () => {});expect(await readdir(workDirectory)).toEqual([]);});++ it('copies the template lockfile and leaves its root entry for yarn install to rename', async () => {+ const template = join(root, 'template');+ const lockfile =+ '"TO-BE-GENERATED@workspace:.":\n version: 0.0.0-use.local\n resolution: "TO-BE-GENERATED@workspace:."\n';++ await cp(TEMPLATE_DIRECTORY, template, { recursive: true });+ await writeFile(join(template, 'yarn.lock'), lockfile);+ vi.mocked(getAppTemplateDirectory).mockReturnValue(template);++ const result = await runJson(['my-app']);++ expect(result.exitCode).toBe(0);+ expect(+ await readFile(join(workDirectory, 'my-app', 'yarn.lock'), 'utf8'),+ ).toBe(lockfile);+ });});