An open source design system that's fully customizable and agent ready
TypeScript
fix: make staged writes portable across filesystems (#6287)
Joey72ce440acadf
diff --git a/.changeset/portable-hardlink-fallback.md b/.changeset/portable-hardlink-fallback.mdnew file mode 100644index 0000000000..fd558d29e5--- /dev/null+++ b/.changeset/portable-hardlink-fallback.md@@ -0,0 +1,11 @@+---+'@astryxdesign/cli': patch+---++[fix] Make staged writes portable across filesystems that reject hard links.+The create-only publisher now falls back from `linkSync` to `copyFileSync` with+`COPYFILE_EXCL` for `EPERM` and `EXDEV`, while preserving no-clobber,+concurrent-creator safety, compare-and-swap replacements, symlink rejection,+rollback, and temporary-file cleanup.++@josephfarinadiff --git a/packages/cli/api/integration/add-helpers.mjs b/packages/cli/api/integration/add-helpers.mjsindex 0cd1838986..2a7a5131fd 100644--- a/packages/cli/api/integration/add-helpers.mjs+++ b/packages/cli/api/integration/add-helpers.mjs@@ -13,6 +13,7 @@ import * as fs from 'node:fs';import * as path from 'node:path';import {randomUUID} from 'node:crypto';import {AstryxError} from '../error.mjs';+import {publishNewFile} from '../../foundation/fs/publish-file.mjs';import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';/** @param {string} value */@@ -310,7 +311,7 @@ export function applyWrites(plans) {for (const plan of staged) {if (plan.original == null) {- fs.linkSync(plan.temporary, plan.path);+ publishNewFile(plan.temporary, plan.path);published.push(plan);removeTemporary(plan.temporary);continue;diff --git a/packages/cli/api/theme/palette/generate/generate.mjs b/packages/cli/api/theme/palette/generate/generate.mjsindex 80e2a1110e..dc27a7b29d 100644--- a/packages/cli/api/theme/palette/generate/generate.mjs+++ b/packages/cli/api/theme/palette/generate/generate.mjs@@ -6,6 +6,7 @@ import {assertWithin,PathSafetyError,} from '../../../../foundation/fs/path-safety.mjs';+import {publishNewFile} from '../../../../foundation/fs/publish-file.mjs';import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';import {AstryxError} from '../../../error.mjs';import {@@ -259,7 +260,7 @@ function writeFilesAtomically(files, overwrite) {} else {// Publishing by hard link is an atomic no-replace operation. A target// created after the initial existence check therefore remains safe.- fs.linkSync(file.temporary, file.path);+ publishNewFile(file.temporary, file.path);file.published = true;fs.unlinkSync(file.temporary);}diff --git a/packages/cli/foundation/fs/publish-file-eperm-mutation.test.mjs b/packages/cli/foundation/fs/publish-file-eperm-mutation.test.mjsnew file mode 100644index 0000000000..aaf68e34f7--- /dev/null+++ b/packages/cli/foundation/fs/publish-file-eperm-mutation.test.mjs@@ -0,0 +1,62 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Mutation test that forces fs.linkSync to throw EPERM so the fallback+ * path is exercised even when the destination already exists. Proves+ * COPYFILE_EXCL is the no-clobber gate.+ *+ * Separate file because vi.mock is hoisted and affects the whole module.+ */++import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';+import * as path from 'node:path';+import * as os from 'node:os';+import * as realFs from 'node:fs';++vi.mock('node:fs', async importOriginal => {+ const actual = await importOriginal();+ return {+ ...actual,+ linkSync: vi.fn(() => {+ const err = new Error('EPERM: operation not permitted, link');+ err.code = 'EPERM';+ throw err;+ }),+ };+});++const {publishNewFile} = await import('./publish-file.mjs');+const fs = await import('node:fs');++let tmpDir;+beforeEach(() => {+ tmpDir = realFs.mkdtempSync(path.join(os.tmpdir(), 'astryx-publish-eperm-'));+});+afterEach(() => {+ realFs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('publishNewFile — forced EPERM fallback', () => {+ it('preserves an existing destination through COPYFILE_EXCL', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const dest = path.join(tmpDir, 'victim.txt');+ realFs.writeFileSync(tmp, 'attacker-content');+ realFs.writeFileSync(dest, 'victim-content');++ expect(() => publishNewFile(tmp, dest)).toThrow(+ expect.objectContaining({code: 'EEXIST'}),+ );+ expect(realFs.readFileSync(dest, 'utf-8')).toBe('victim-content');+ expect(fs.linkSync).toHaveBeenCalledOnce();+ });++ it('publishes a new destination through the fallback', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const dest = path.join(tmpDir, 'new-file.txt');+ realFs.writeFileSync(tmp, 'new-content');++ expect(() => publishNewFile(tmp, dest)).not.toThrow();+ expect(realFs.readFileSync(dest, 'utf-8')).toBe('new-content');+ expect(fs.linkSync).toHaveBeenCalled();+ });+});diff --git a/packages/cli/foundation/fs/publish-file-hardlink-unavailable.test.mjs b/packages/cli/foundation/fs/publish-file-hardlink-unavailable.test.mjsnew file mode 100644index 0000000000..8e100cfc5f--- /dev/null+++ b/packages/cli/foundation/fs/publish-file-hardlink-unavailable.test.mjs@@ -0,0 +1,107 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Optional integration proof for filesystems that reject hard links.+ * Set ASTRYX_HARDLINK_UNAVAILABLE_TEST_ROOT to a writable directory on such a+ * filesystem to exercise the real fallback end to end.+ */++import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {applyWrites} from '../../api/integration/add-helpers.mjs';++const testRoot = process.env.ASTRYX_HARDLINK_UNAVAILABLE_TEST_ROOT ?? null;++describe.skipIf(!testRoot)(+ 'hard-link-unavailable filesystem integration proof',+ () => {+ let testDir;++ beforeEach(() => {+ testDir = fs.mkdtempSync(path.join(testRoot, '.astryx-publish-proof-'));+ });++ afterEach(() => {+ fs.rmSync(testDir, {recursive: true, force: true});+ });++ it('confirms the configured filesystem rejects hard links', () => {+ const source = path.join(testDir, '.tmp-source');+ const destination = path.join(testDir, '.tmp-destination');+ fs.writeFileSync(source, 'link-test');++ expect(() => fs.linkSync(source, destination)).toThrow(+ expect.objectContaining({code: expect.stringMatching(/^(EPERM|EXDEV)$/)}),+ );+ });++ it('applyWrites creates files through the fallback', () => {+ const plans = [+ {+ path: path.join(testDir, 'MyComponent.tsx'),+ contents: '// MyComponent\nexport default function MyComponent() {}\n',+ createOnly: true,+ },+ {+ path: path.join(testDir, 'MyComponent.test.tsx'),+ contents: '// test\nimport MyComponent from "./MyComponent";\n',+ createOnly: true,+ },+ ];++ const rollback = applyWrites(plans);+ expect(typeof rollback).toBe('function');+ expect(fs.readFileSync(plans[0].path, 'utf-8')).toContain('MyComponent');+ expect(fs.readFileSync(plans[1].path, 'utf-8')).toContain('test');+ });++ it('applyWrites preserves no-clobber behavior', () => {+ const target = path.join(testDir, 'existing.tsx');+ fs.writeFileSync(target, '// original\n');++ expect(() =>+ applyWrites([+ {+ path: target,+ contents: '// replacement\n',+ createOnly: true,+ },+ ]),+ ).toThrow(/overwrite|exists/i);+ expect(fs.readFileSync(target, 'utf-8')).toBe('// original\n');+ });++ it('applyWrites rolls back partial publication', () => {+ const good = path.join(testDir, 'good.tsx');+ const bad = path.join(testDir, 'bad.tsx');+ fs.writeFileSync(bad, '// preexisting\n');++ expect(() =>+ applyWrites([+ {path: good, contents: '// good file\n', createOnly: true},+ {path: bad, contents: '// replacement\n', createOnly: true},+ ]),+ ).toThrow();+ expect(fs.existsSync(good)).toBe(false);+ expect(fs.readFileSync(bad, 'utf-8')).toBe('// preexisting\n');+ });++ it('applyWrites keeps compare-and-swap replacement behavior', () => {+ const target = path.join(testDir, 'config.json');+ const original = '{"version": 1}\n';+ fs.writeFileSync(target, original);++ const rollback = applyWrites([+ {+ path: target,+ contents: '{"version": 2}\n',+ createOnly: false,+ expectedOriginal: Buffer.from(original),+ },+ ]);+ expect(typeof rollback).toBe('function');+ expect(fs.readFileSync(target, 'utf-8')).toBe('{"version": 2}\n');+ });+ },+);diff --git a/packages/cli/foundation/fs/publish-file.mjs b/packages/cli/foundation/fs/publish-file.mjsnew file mode 100644index 0000000000..9f77cd0ff4--- /dev/null+++ b/packages/cli/foundation/fs/publish-file.mjs@@ -0,0 +1,68 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Portable create-only file publication.+ *+ * @input A fully written temporary file and a destination path.+ * @output The destination exists with the temporary's content, or an error+ * is thrown and nothing is created.+ * @position foundation/fs — used by every write transaction that creates a+ * new file without overwriting (integration add, palette generation,+ * manifest creation).+ *+ * The ideal primitive is `fs.linkSync`: it is a single atomic directory-entry+ * operation that fails with EEXIST when the destination already exists, giving+ * concurrent-creator safety for free.+ *+ * Some virtual, network, and cross-device filesystems reject hard links with+ * EPERM or EXDEV. When that happens, we fall back to `fs.copyFileSync` with+ * `COPYFILE_EXCL`, which creates the destination with O_EXCL (still fails+ * EEXIST on collision) and copies the content.+ *+ * SYNC: residual crash-atomicity tradeoff — `linkSync` adds a directory+ * entry in a single metadata operation, so a crash cannot produce a partial+ * file. `copyFileSync` writes data, so a crash mid-copy could leave a+ * truncated destination. Callers that need crash-atomic guarantees on+ * link-hostile filesystems would need `fsync` + rename, which conflicts+ * with the no-clobber requirement. For CLI-driven interactive writes the+ * window is negligible and the tradeoff is accepted.+ */++import * as fs from 'node:fs';++/**+ * Publish a fully written temporary file to a new destination path.+ *+ * Semantics:+ * - **Create-only**: if `destination` already exists, throws with+ * `code === 'EEXIST'` and leaves the existing file untouched.+ * - **Concurrent-creator safe**: two racing publishers to the same+ * destination — at most one wins; the loser gets EEXIST.+ * - **Symlink-neutral**: this function does not follow or reject+ * symlinks at `destination`; callers that need symlink rejection+ * must check before calling.+ *+ * The temporary file is NOT removed by this function — the caller+ * owns cleanup so that rollback paths can still read it.+ *+ * @param {string} temporary Fully written source (temp) file path.+ * @param {string} destination Target path that must not yet exist.+ */+export function publishNewFile(temporary, destination) {+ try {+ fs.linkSync(temporary, destination);+ } catch (linkError) {+ if (+ linkError &&+ typeof linkError === 'object' &&+ 'code' in linkError &&+ (linkError.code === 'EPERM' || linkError.code === 'EXDEV')+ ) {+ // Hard links unavailable (EPERM) or cross-device (EXDEV).+ // Fall back to exclusive-create copy: O_EXCL guarantees no-clobber.+ fs.copyFileSync(temporary, destination, fs.constants.COPYFILE_EXCL);+ return;+ }+ throw linkError;+ }+}diff --git a/packages/cli/foundation/fs/publish-file.test.mjs b/packages/cli/foundation/fs/publish-file.test.mjsnew file mode 100644index 0000000000..d9d2a95a99--- /dev/null+++ b/packages/cli/foundation/fs/publish-file.test.mjs@@ -0,0 +1,136 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import * as os from 'node:os';+import {publishNewFile} from './publish-file.mjs';++let tmpDir;+beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-publish-file-'));+});+afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('publishNewFile', () => {+ it('publishes a new file from a temporary', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const dest = path.join(tmpDir, 'output.txt');+ fs.writeFileSync(tmp, 'hello');+ publishNewFile(tmp, dest);+ expect(fs.readFileSync(dest, 'utf-8')).toBe('hello');+ });++ it('preserves content fidelity for binary data', () => {+ const tmp = path.join(tmpDir, '.tmp-bin');+ const dest = path.join(tmpDir, 'output.bin');+ const buf = Buffer.from([0x00, 0xff, 0x80, 0x01, 0xfe]);+ fs.writeFileSync(tmp, buf);+ publishNewFile(tmp, dest);+ expect(fs.readFileSync(dest).equals(buf)).toBe(true);+ });++ it('does not remove the temporary file', () => {+ const tmp = path.join(tmpDir, '.tmp-keep');+ const dest = path.join(tmpDir, 'output.txt');+ fs.writeFileSync(tmp, 'data');+ publishNewFile(tmp, dest);+ expect(fs.existsSync(tmp)).toBe(true);+ });++ it('throws EEXIST when the destination already exists', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const dest = path.join(tmpDir, 'existing.txt');+ fs.writeFileSync(tmp, 'new');+ fs.writeFileSync(dest, 'old');+ expect(() => publishNewFile(tmp, dest)).toThrow(+ expect.objectContaining({code: 'EEXIST'}),+ );+ expect(fs.readFileSync(dest, 'utf-8')).toBe('old');+ });++ it('protects existing content on collision', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const dest = path.join(tmpDir, 'existing.txt');+ fs.writeFileSync(tmp, 'attacker');+ fs.writeFileSync(dest, 'victim');+ expect(() => publishNewFile(tmp, dest)).toThrow();+ expect(fs.readFileSync(dest, 'utf-8')).toBe('victim');+ });++ it('allows exactly one of two creators to publish', () => {+ const tmp1 = path.join(tmpDir, '.tmp-a');+ const tmp2 = path.join(tmpDir, '.tmp-b');+ const dest = path.join(tmpDir, 'contested.txt');+ fs.writeFileSync(tmp1, 'creator-a');+ fs.writeFileSync(tmp2, 'creator-b');++ publishNewFile(tmp1, dest);+ expect(() => publishNewFile(tmp2, dest)).toThrow(+ expect.objectContaining({code: 'EEXIST'}),+ );+ expect(fs.readFileSync(dest, 'utf-8')).toBe('creator-a');+ });++ it('re-throws ENOENT when the temporary does not exist', () => {+ const tmp = path.join(tmpDir, '.tmp-missing');+ const dest = path.join(tmpDir, 'output.txt');+ expect(() => publishNewFile(tmp, dest)).toThrow(+ expect.objectContaining({code: 'ENOENT'}),+ );+ });++ it('does not follow a symlink destination', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const real = path.join(tmpDir, 'real.txt');+ const sym = path.join(tmpDir, 'sym.txt');+ fs.writeFileSync(tmp, 'data');+ fs.writeFileSync(real, 'original');+ fs.symlinkSync(real, sym);+ expect(() => publishNewFile(tmp, sym)).toThrow();+ expect(fs.readFileSync(real, 'utf-8')).toBe('original');+ });++ it('publishes a readable file', () => {+ const tmp = path.join(tmpDir, '.tmp-src');+ const dest = path.join(tmpDir, 'readable.txt');+ fs.writeFileSync(tmp, 'check-perms');+ publishNewFile(tmp, dest);+ const stat = fs.statSync(dest);+ expect(stat.mode & 0o444).toBeGreaterThan(0);+ });++ const hasWritableVarTmp = (() => {+ try {+ return os.platform() === 'linux' && fs.existsSync('/var/tmp');+ } catch {+ return false;+ }+ })();++ it.skipIf(!hasWritableVarTmp)(+ 'falls back to COPYFILE_EXCL when a cross-device link returns EXDEV',+ () => {+ const source = path.join(tmpDir, '.cross-src');+ fs.writeFileSync(source, 'cross-device-content');++ let otherDir;+ try {+ otherDir = fs.mkdtempSync('/var/tmp/astryx-xdev-');+ } catch {+ return;+ }+ try {+ const destination = path.join(otherDir, 'output.txt');+ publishNewFile(source, destination);+ expect(fs.readFileSync(destination, 'utf-8')).toBe(+ 'cross-device-content',+ );+ } finally {+ fs.rmSync(otherDir, {recursive: true, force: true});+ }+ },+ );+});diff --git a/packages/cli/foundation/integrations/manifest-writer.mjs b/packages/cli/foundation/integrations/manifest-writer.mjsindex df1b6cce28..474c9b721e 100644--- a/packages/cli/foundation/integrations/manifest-writer.mjs+++ b/packages/cli/foundation/integrations/manifest-writer.mjs@@ -12,6 +12,7 @@import * as fs from 'node:fs';import * as path from 'node:path';import {randomUUID} from 'node:crypto';+import {publishNewFile} from '../fs/publish-file.mjs';import jscodeshift from 'jscodeshift';import {assertWithin} from '../fs/path-safety.mjs';import {findManifestPaths, loadManifestObject} from './integrations.mjs';@@ -181,7 +182,7 @@ function createFile(file, contents) {fs.writeFileSync(descriptor, contents, 'utf-8');fs.closeSync(descriptor);descriptor = undefined;- fs.linkSync(temporary, file);+ publishNewFile(temporary, file);linked = true;removeTemporary(temporary);} catch (error) {