Skip to content

The open alternative to Salesforce, designed for AI.

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.md
index 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 of
its CLI runs fails or times out, or when `app init` would pin versions that are
not on npm. An unreachable registry is reported separately from a missing
version. 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:
```bash
yarn nx build twenty-cli
node packages/twenty-cli/scripts/check-publish.mjs
+node packages/twenty-cli/scripts/generate-template-lock.mjs
```
## App integration tests
diff --git a/packages/twenty-cli/docs/commands.md b/packages/twenty-cli/docs/commands.md
index 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-app
twenty 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.json
index 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.json
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.ts
index 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.ts
index 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);
+ });
});