Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/integration/add-helpers.mjs b/packages/cli/api/integration/add-helpers.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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) {