An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* The measurement build root, against a real pnpm virtual store.
*
* The measurer's build must not touch the sandbox it measures: that tree is the
* attested artifact, and a build in place regenerates the app-owned theme,
* writes `dist/`, appends to the CLI's invocation log, and caches into
* `node_modules`, after which the cell no longer hashes to its own digest.
*
* A pnpm `node_modules` makes that harder than copying files, because it is
* mostly links into a virtual store:
*
* node_modules/is-odd -> .pnpm/[email protected]/node_modules/is-odd
* node_modules/.pnpm/<id>/... the real package trees
* node_modules/.modules.yaml the store's own state
*
* Mirroring `.pnpm` with a symlink — which is what this did first — hands the
* copy a door back into the original: an install or rebuild that rewrites the
* store writes straight through it. These cases use a real `pnpm install` for
* the fixture rather than a hand-drawn imitation, because the shape is the
* thing being tested.
*
* The cases are the guarantee, not the construction: the sandbox is unchanged
* after a build in the copy, the copy is a working tree, and the isolation
* check catches both ways of getting it wrong. How the copier achieves that is
* deliberately not asserted.
*/
import {execFileSync, spawnSync} from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {afterAll, afterEach, beforeAll, describe, expect, it} from 'vitest';
import {measurementPrivateValues, publicMeasurement} from './setup-measure.mjs';
import {
createMeasurementWorkspace,
manifestDifferences,
retargetEscapingLinks,
treeManifest,
verifyWorkspaceIsolation,
} from './setup-workspace.mjs';
const temporaryDirectories = [];
/** One real install, reused: the shape is what matters, not the download. */
let installedFixture = null;
function temporary(prefix) {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
temporaryDirectories.push(directory);
return directory;
}
function write(root, relativePath, content, mode) {
const file = path.join(root, relativePath);
fs.mkdirSync(path.dirname(file), {recursive: true});
fs.writeFileSync(file, content);
if (mode !== undefined) fs.chmodSync(file, mode);
}
function pnpm(args, cwd) {
return spawnSync('pnpm', args, {
cwd,
encoding: 'utf8',
env: {...process.env, CI: 'true'},
stdio: ['ignore', 'pipe', 'pipe'],
});
}
/** Whether a real pnpm is reachable; without one these cases cannot run. */
function pnpmAvailable() {
const result = pnpm(['--version'], os.tmpdir());
return result.status === 0 && /^\d+\./.test((result.stdout ?? '').trim());
}
const HAS_PNPM = pnpmAvailable();
const describeWithPnpm = HAS_PNPM ? describe : describe.skip;
/**
* A sandbox with a real pnpm `node_modules`, plus the files a measured arm
* carries: a committed generated theme artifact, ignored build output, the
* CLI's invocation log, an executable script, and a link out to a workspace
* package.
*/
function installedSandbox() {
if (!installedFixture) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-workspace-src-'));
temporaryDirectories.push(root);
const app = path.join(root, 'app');
fs.mkdirSync(app, {recursive: true});
write(
app,
'package.json',
`${JSON.stringify(
{
name: 'host',
private: true,
// `is-odd` pulls `is-number`, so the store has a package that depends
// on another one and the relative link between them is exercised.
dependencies: {'is-odd': '3.0.1'},
scripts: {build: 'node build.mjs'},
},
null,
2,
)}\n`,
);
const install = pnpm(['install', '--ignore-scripts'], app);
if (install.status !== 0) {
throw new Error(`fixture install failed: ${install.stderr}`);
}
installedFixture = {root, app};
}
// Each case gets its own copy of that installed tree, so one case's install
// cannot be seen by the next.
const root = temporary('setup-workspace-test-');
const app = path.join(root, 'app');
execFileSync('cp', ['-a', '--reflink=auto', installedFixture.app, app]);
write(app, '.gitignore', 'node_modules/\ndist/\n');
write(app, 'index.html', '<!doctype html>\n<html lang="en"></html>\n');
write(app, 'src/App.tsx', 'export const App = () => null;\n');
write(app, 'src/index.css', "@import 'tailwindcss';\n");
write(
app,
'src/apptheme.css',
'/* @generated by `astryx theme build` */\n:root { color-scheme: light dark; }\n',
);
write(app, 'src/apptheme.d.ts', 'export declare const theme: unknown;\n');
write(app, 'dist/index.html', '<!doctype html>\n');
write(app, 'dist/assets/app.css', '@layer reset, theme;\n');
write(app, '.astryx-invocations.log', 'theme build\n');
write(app, 'scripts/run.sh', '#!/bin/sh\necho ok\n', 0o755);
fs.symlinkSync('./index.css', path.join(app, 'src/alias.css'));
// A workspace package linked in by absolute path, the way the canonical
// harness links the design system's own source into an arm.
const workspace = path.join(root, 'workspace-package');
fs.mkdirSync(workspace, {recursive: true});
write(workspace, 'package.json', '{"name": "@scope/workspace"}\n');
fs.mkdirSync(path.join(app, 'node_modules/@scope'), {recursive: true});
fs.symlinkSync(workspace, path.join(app, 'node_modules/@scope/workspace'));
return {root, app, workspace};
}
/**
* A build script that does to its own tree exactly what a real one does:
* regenerate the theme, write dist, append to the log, cache in node_modules.
*/
function withBuildScript(app, {fails = false} = {}) {
write(
app,
'build.mjs',
[
"import * as fs from 'node:fs';",
// A build that finds no TTY must not ask anything or fall over.
"if (process.stdout.isTTY) throw new Error('unexpected TTY');",
"fs.writeFileSync('src/apptheme.css', '/* rebuilt */\\n');",
"fs.mkdirSync('dist/assets', {recursive: true});",
"fs.writeFileSync('dist/index.html', '<!doctype html>\\n');",
"fs.writeFileSync('dist/assets/app.css', '@layer reset, theme;\\n');",
"fs.appendFileSync('.astryx-invocations.log', 'build\\n');",
"fs.mkdirSync('node_modules/.vite', {recursive: true});",
"fs.writeFileSync('node_modules/.vite/cache.json', '{}\\n');",
// Rewrite a file inside the virtual store, which is the write that used
// to reach the original through the mirrored `.pnpm` link.
"fs.writeFileSync('node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js', 'module.exports = 1;\\n');",
...(fails ? ['process.exit(1);'] : []),
].join('\n'),
);
}
/** The whole tree, hashed — including every file in the virtual store. */
const manifest = root => treeManifest(root);
afterEach(() => {
while (temporaryDirectories.length > 0) {
const directory = temporaryDirectories.pop();
if (installedFixture && directory === installedFixture.root) continue;
fs.rmSync(directory, {recursive: true, force: true});
}
});
afterAll(() => {
if (installedFixture) {
fs.rmSync(installedFixture.root, {recursive: true, force: true});
installedFixture = null;
}
});
describeWithPnpm('measurement build root over a pnpm virtual store', () => {
beforeAll(() => {
// Warm the shared install once so the first case is not timed with it.
installedSandbox();
}, 300_000);
it.each([
{name: 'a build that succeeds', fails: false},
{name: 'a build that fails', fails: true},
])(
'leaves the sandbox byte-identical after $name in the copy',
({fails}) => {
const {app} = installedSandbox();
withBuildScript(app, {fails});
const before = manifest(app);
const copy = createMeasurementWorkspace(app);
const result = pnpm(['build'], copy.dir);
expect(result.status).toBe(fails ? 1 : 0);
// Non-interactive: nothing complained about a missing terminal.
expect(`${result.stdout}${result.stderr}`).not.toMatch(/TTY|tty/);
// The build really did write, in the copy — including into the virtual
// store, which is the write that used to reach the original.
expect(
fs.readFileSync(path.join(copy.dir, 'src/apptheme.css'), 'utf8'),
).toBe('/* rebuilt */\n');
expect(
fs.readFileSync(
path.join(
copy.dir,
'node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js',
),
'utf8',
),
).toBe('module.exports = 1;\n');
// And none of it reached the sandbox, virtual store included.
expect(manifestDifferences(before, manifest(app))).toEqual([]);
copy.cleanup();
expect(manifestDifferences(before, manifest(app))).toEqual([]);
},
300_000,
);
it('survives an install in the copy recreating the whole virtual store', () => {
const {app} = installedSandbox();
const before = manifest(app);
const copy = createMeasurementWorkspace(app);
// The strongest case: throw the copy's store away and have pnpm rebuild
// it. Through a mirrored `.pnpm` link this would have deleted and rewritten
// the sandbox's own store.
fs.rmSync(path.join(copy.dir, 'node_modules/.pnpm'), {
recursive: true,
force: true,
});
const install = pnpm(['install', '--ignore-scripts'], copy.dir);
expect(install.status, install.stderr).toBe(0);
expect(manifestDifferences(before, manifest(app))).toEqual([]);
copy.cleanup();
expect(manifestDifferences(before, manifest(app))).toEqual([]);
}, 300_000);
it('hands back a working tree, resolving inside itself', () => {
const {app, workspace: workspacePackage} = installedSandbox();
const copy = createMeasurementWorkspace(app);
// Module resolution works from the copy, and lands in the copy.
const resolved = spawnSync(
process.execPath,
['-e', "process.stdout.write(require.resolve('is-odd'))"],
{cwd: copy.dir, encoding: 'utf8'},
);
expect(resolved.status, resolved.stderr).toBe(0);
expect(resolved.stdout.startsWith(fs.realpathSync(copy.dir))).toBe(true);
// A link out to a workspace package is left pointing where it pointed: it
// is not the sandbox, and rewriting it would break resolution.
expect(
fs.realpathSync(path.join(copy.dir, 'node_modules/@scope/workspace')),
).toBe(fs.realpathSync(workspacePackage));
// Nothing anywhere in the copy can reach the sandbox.
expect(verifyWorkspaceIsolation(copy.dir, app, {full: true})).toEqual([]);
copy.cleanup();
}, 120_000);
it('copies the same way on a platform without a usable cp', () => {
// The pure-Node copier is a second implementation of the same guarantee,
// and no other case reaches it.
const {app} = installedSandbox();
const before = manifest(app);
const copy = createMeasurementWorkspace(app, {strategy: 'node'});
expect(verifyWorkspaceIsolation(copy.dir, app, {full: true})).toEqual([]);
fs.writeFileSync(
path.join(
copy.dir,
'node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js',
),
'module.exports = 2;\n',
);
expect(manifestDifferences(before, manifest(app))).toEqual([]);
copy.cleanup();
}, 300_000);
it('removes the build root even when the measurement throws', () => {
const {app} = installedSandbox();
const before = manifest(app);
const copy = createMeasurementWorkspace(app);
expect(() => {
try {
fs.writeFileSync(path.join(copy.dir, 'dist/index.html'), 'partial\n');
throw new Error('measurement failed');
} finally {
copy.cleanup();
}
}).toThrow('measurement failed');
expect(fs.existsSync(copy.dir)).toBe(false);
expect(manifestDifferences(before, manifest(app))).toEqual([]);
}, 120_000);
});
/**
* The mutations: build the copy the two wrong ways and show each is caught.
*
* Without these the cases above could be passing for the wrong reason. There
* are exactly two ways for a copy to stay reachable from the sandbox — a link
* that resolves back into it, and a file that shares its inode — so there is
* one mutation for each, and no more.
*/
describeWithPnpm('a copy that is not a copy is caught', () => {
it('mirroring the virtual store writes through, and is reported', () => {
const {app} = installedSandbox();
const packageFile =
'node_modules/.pnpm/[email protected]/node_modules/is-odd/index.js';
const before = manifest(app);
// The defective copier: real dirs, but `node_modules` entries symlinked
// back at the original — which for pnpm means the whole virtual store.
const mirrored = path.join(temporary('setup-workspace-mutation-'), 'app');
fs.mkdirSync(mirrored, {recursive: true});
for (const entry of fs.readdirSync(app, {withFileTypes: true})) {
const from = path.join(app, entry.name);
const to = path.join(mirrored, entry.name);
if (entry.name === 'node_modules') {
fs.mkdirSync(to, {recursive: true});
for (const inner of fs.readdirSync(from, {withFileTypes: true})) {
fs.symlinkSync(path.join(from, inner.name), path.join(to, inner.name));
}
continue;
}
if (entry.isSymbolicLink()) {
fs.symlinkSync(fs.readlinkSync(from), to);
continue;
}
if (entry.isDirectory()) {
execFileSync('cp', ['-a', from, to]);
continue;
}
fs.copyFileSync(from, to);
}
// `.pnpm` is a link to the original store, so this write lands there.
fs.writeFileSync(
path.join(mirrored, packageFile),
'module.exports = "written through";\n',
);
expect(
manifestDifferences(before, manifest(app)).join('\n'),
).toMatch(/changed: node_modules\/\.pnpm\//);
// And the isolation check refuses that construction, so a change that
// reintroduces mirroring cannot ship quietly.
expect(verifyWorkspaceIsolation(mirrored, app).join('\n')).toMatch(
/symlink escapes to the sandbox: node_modules\/\.pnpm/,
);
}, 120_000);
it('hardlinking instead of copying is reported', () => {
const {app} = installedSandbox();
const dir = path.join(temporary('setup-workspace-hardlink-'), 'app');
// The other way to get this wrong: the bytes look right and the inode is
// shared, so a rewrite in the copy reaches the original.
execFileSync('cp', ['-al', app, dir]);
expect(
verifyWorkspaceIsolation(dir, app, {full: true}).join('\n'),
).toMatch(/shares an inode with the sandbox/);
}, 120_000);
});
/**
* The manifest is the instrument every proof above depends on, so it has to be
* able to fail. A build's own writes are covered end to end by those cases;
* these are the two differences a content hash alone would miss.
*/
describe('tree manifest', () => {
function plainSandbox() {
const app = path.join(temporary('setup-manifest-test-'), 'app');
write(app, 'src/App.tsx', 'export const App = () => null;\n');
write(app, 'scripts/run.sh', '#!/bin/sh\n', 0o755);
return app;
}
it.each([
{
name: 'a file touched without its bytes changing',
mutate: app => {
const when = new Date(Date.now() + 5_000);
fs.utimesSync(path.join(app, 'src/App.tsx'), when, when);
},
expected: /changed: src\/App\.tsx/,
},
{
name: 'a file whose mode changed and nothing else',
mutate: app => fs.chmodSync(path.join(app, 'scripts/run.sh'), 0o644),
expected: /changed: scripts\/run\.sh/,
},
])('reports $name', ({mutate, expected}) => {
const app = plainSandbox();
const before = manifest(app);
mutate(app);
expect(manifestDifferences(before, manifest(app)).join('\n')).toMatch(
expected,
);
});
});
describe('build root boundaries', () => {
it('redacts the build root as well as the sandbox', () => {
const root = temporary('setup-redaction-test-');
const app = path.join(root, 'app');
write(app, 'package.json', '{"name": "host"}\n');
const workspace = createMeasurementWorkspace(app);
const privateValues = measurementPrivateValues({
appDir: app,
outFile: path.join(root, 'measurement.json'),
buildDir: workspace.dir,
});
expect(privateValues).toContain(workspace.dir);
expect(privateValues).toContain(path.dirname(workspace.dir));
const exported = publicMeasurement(
{
label: 'arm',
app,
build: {
ok: false,
status: 1,
ms: 1,
stdout: `building in ${workspace.dir}\n`,
stderr: `failed in ${workspace.dir}/src\n`,
},
schemes: {},
},
{fixtureId: 'enterprise-scoped-synthetic', privateValues},
);
const serialized = JSON.stringify(exported);
expect(serialized).not.toContain(workspace.dir);
expect(serialized).not.toContain(path.dirname(workspace.dir));
expect(serialized).not.toContain(app);
expect(exported.app).toBe('enterprise-scoped-synthetic');
workspace.cleanup();
});
it('moves only the links that would escape, and leaves the rest alone', () => {
const root = temporary('setup-retarget-test-');
const app = path.join(root, 'app');
write(app, 'package.json', '{"name": "host"}\n');
write(app, 'src/index.css', 'body {}\n');
fs.symlinkSync('./index.css', path.join(app, 'src/relative.css'));
fs.symlinkSync(
path.join(app, 'src/index.css'),
path.join(app, 'absolute.css'),
);
// An absolute link to somewhere that is not the sandbox stays as it is.
write(root, 'outside.txt', 'shared\n');
fs.symlinkSync(
path.join(root, 'outside.txt'),
path.join(app, 'outside.txt'),
);
const copy = path.join(root, 'copy');
execFileSync('cp', ['-a', app, copy]);
const rewritten = retargetEscapingLinks(copy, app);
expect(fs.readlinkSync(path.join(copy, 'src/relative.css'))).toBe(
'./index.css',
);
expect(fs.readlinkSync(path.join(copy, 'absolute.css'))).toBe(
path.join(copy, 'src/index.css'),
);
expect(fs.readlinkSync(path.join(copy, 'outside.txt'))).toBe(
path.join(root, 'outside.txt'),
);
expect(rewritten.map(entry => path.relative(copy, entry.link))).toEqual([
'absolute.css',
]);
});
it('refuses a sandbox that is not there, and cleans up idempotently', () => {
expect(() =>
createMeasurementWorkspace(path.join(os.tmpdir(), 'no-such-sandbox-xyz')),
).toThrow(/does not exist/);
const app = path.join(temporary('setup-cleanup-test-'), 'app');
write(app, 'package.json', '{"name": "host"}\n');
const workspace = createMeasurementWorkspace(app);
workspace.cleanup();
expect(() => workspace.cleanup()).not.toThrow();
});
});
/**
* `--reflink` is GNU coreutils only. A BSD or busybox `cp` rejects it outright
* — nonzero, nothing copied — and that is a platform, not a fault, so it has
* to reach the pure-Node copier the same way a missing `cp` does. The
* distinction that matters is the other one: a `cp` that took the flag and
* then failed part way through has left debris, and must not be quietly
* copied over.
*/
describe('a cp that does not support --reflink', () => {
/**
* Put a fake `cp` first on PATH. It writes `left-behind.txt` into the
* destination before failing, so a fallback that did not clear the
* destination first would be visible in the finished copy.
*/
function shimCp(script) {
const bin = temporary('setup-cp-shim-');
const shim = path.join(bin, 'cp');
fs.writeFileSync(
shim,
[
'#!/bin/sh',
'dest=""',
'for arg in "$@"; do dest="$arg"; done',
'mkdir -p "$dest"',
'printf %s "debris" > "$dest/left-behind.txt"',
script,
].join('\n'),
);
fs.chmodSync(shim, 0o755);
const original = process.env.PATH;
process.env.PATH = `${bin}${path.delimiter}${original}`;
return () => {
process.env.PATH = original;
};
}
function plainSandbox() {
const app = path.join(temporary('setup-reflink-test-'), 'app');
write(app, 'package.json', '{"name": "host"}\n');
write(app, 'src/index.css', 'body {}\n');
write(app, 'scripts/run.sh', '#!/bin/sh\necho ok\n', 0o755);
fs.symlinkSync('./index.css', path.join(app, 'src/alias.css'));
return app;
}
it('falls back to a complete copy instead of failing the measurement', () => {
const app = plainSandbox();
const restore = shimCp(
[
// What busybox says; BSD `cp` says `illegal option` and a usage line.
'echo "cp: unrecognized option \'--reflink=auto\'" >&2',
'exit 1',
].join('\n'),
);
try {
const copy = createMeasurementWorkspace(app);
// A real copy: contents, modes and symlink text all came across.
expect(fs.readFileSync(path.join(copy.dir, 'src/index.css'), 'utf8')).toBe(
'body {}\n',
);
expect(
fs.lstatSync(path.join(copy.dir, 'scripts/run.sh')).mode & 0o777,
).toBe(0o755);
expect(fs.readlinkSync(path.join(copy.dir, 'src/alias.css'))).toBe(
'./index.css',
);
// The failed attempt's debris was cleared, not copied over.
expect(fs.existsSync(path.join(copy.dir, 'left-behind.txt'))).toBe(false);
expect(verifyWorkspaceIsolation(copy.dir, app, {full: true})).toEqual([]);
copy.cleanup();
} finally {
restore();
}
});
it('still raises a copy that really failed', () => {
const app = plainSandbox();
const restore = shimCp(
['echo "cp: cannot stat \'src\': Input/output error" >&2', 'exit 1'].join(
'\n',
),
);
try {
expect(() => createMeasurementWorkspace(app)).toThrow(
/could not copy the sandbox into a build root: cp: cannot stat/,
);
} finally {
restore();
}
});
});