@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/theme/add/add.mjs

@@ -15,6 +15,7 @@ import {
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {listAvailableThemes, findTheme} from '../_adapter.mjs';
+import {applyWrites} from '../../integration/add-helpers.mjs';
 // Scaffolded files must not carry our repo boilerplate into a consumer's tree.
 import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
 
@@ -26,6 +27,20 @@ function defaultTargetDir(slug) {
   return path.join('src', 'themes', slug);
 }
 
+/**
+ * The bytes to write for one listed file. Only UTF-8 text loses our header;
+ * anything else (a font, an image) is copied verbatim, since decoding it would
+ * corrupt it.
+ * @param {Buffer} bytes
+ * @returns {Buffer | string}
+ */
+function scaffoldContents(bytes) {
+  const text = bytes.toString('utf-8');
+  return Buffer.from(text, 'utf-8').equals(bytes)
+    ? stripCopyrightHeader(text)
+    : bytes;
+}
+
 /**
  * Copy a bundled theme's files into the consumer's project (defaults to
  * `src/themes/<slug>/`). Writes are staged to temp files then renamed, rolling
@@ -122,34 +137,28 @@ export async function themeAdd(slug, options = {}) {
     }
   }
 
-  // Stage to temp files then rename, rolling back partials on failure so a
-  // failed write never leaves a half-written theme. mkdir is inside the try so
-  // a failure (e.g. an ancestor is a file → EEXIST/ENOTDIR) surfaces as a
-  // stable ERR_WRITE_FAILED rather than leaking a raw fs errno + absolute path.
-  const staged = [];
+  // One transaction: every file publishes, or every replaced file gets its
+  // previous bytes back and every created file is removed. mkdir is inside the
+  // try so a failure (e.g. an ancestor is a file → EEXIST/ENOTDIR) surfaces as
+  // a stable ERR_WRITE_FAILED rather than leaking a raw fs errno + absolute path.
   try {
     fs.mkdirSync(resolvedDir, {recursive: true});
-    for (const w of writes) {
+    const plans = writes.map(w => {
+      fs.mkdirSync(path.dirname(w.dest), {recursive: true});
+      // Confine again once the directories exist: one may have been swapped
+      // for a link since the destination was first checked.
       const dest = assertWithin(w.name, resolvedDir, {
         label: `theme destination for ${w.name}`,
       });
-      fs.mkdirSync(path.dirname(dest), {recursive: true});
-      const tmp = `${dest}.${process.pid}.tmp`;
-      const contents = stripCopyrightHeader(fs.readFileSync(w.src, 'utf-8'));
-      fs.writeFileSync(tmp, contents);
-      staged.push({tmp, dest});
-    }
-    for (const s of staged) {
-      fs.renameSync(s.tmp, s.dest);
-    }
+      return {
+        path: dest,
+        contents: scaffoldContents(fs.readFileSync(w.src)),
+        createOnly: !overwrite,
+      };
+    });
+    applyWrites(plans);
   } catch (err) {
-    for (const s of staged) {
-      try {
-        fs.rmSync(s.tmp, {force: true});
-      } catch {
-        /* best-effort */
-      }
-    }
+    if (err instanceof AstryxError) throw err;
     if (err instanceof PathSafetyError) {
       throw new AstryxError(
         err.message,

package/api/theme/add/add.rollback.test.mjs

@@ -0,0 +1,158 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * `theme add` writes a theme as one transaction: when a later file fails to
+ * publish, every file it already replaced gets its previous bytes back and
+ * every file it created is removed. Publishing is forced to fail by wrapping
+ * the two calls that publish a staged file: `linkSync` for a new file and
+ * `renameSync` for a replacement.
+ *
+ * Separate file because vi.mock is hoisted and affects the whole module.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const failures = vi.hoisted(() => ({
+  /** Fail the Nth staged-file publish (1-based); 0 disables. */
+  publish: 0,
+  /** Also fail every rollback restore. */
+  restore: false,
+  count: 0,
+}));
+
+vi.mock('node:fs', async importOriginal => {
+  const actual = /** @type {typeof import('node:fs')} */ (
+    await importOriginal()
+  );
+  /** @param {string} source */
+  const isStaged = source => path.basename(String(source)).includes('.tmp');
+  /** @param {string} source */
+  const isRestore = source =>
+    path.basename(String(source)).includes('.restore-');
+  /** @param {string} source @param {string} op */
+  const maybeFail = (source, op) => {
+    if (isStaged(source) && failures.publish > 0) {
+      failures.count++;
+      if (failures.count === failures.publish) {
+        throw Object.assign(new Error(`EIO: forced ${op} failure`), {
+          code: 'EIO',
+        });
+      }
+    }
+    if (isRestore(source) && failures.restore) {
+      throw Object.assign(new Error(`EIO: forced restore failure`), {
+        code: 'EIO',
+      });
+    }
+  };
+  return {
+    ...actual,
+    linkSync: vi.fn((source, destination) => {
+      maybeFail(source, 'link');
+      return actual.linkSync(source, destination);
+    }),
+    renameSync: vi.fn((source, destination) => {
+      maybeFail(source, 'rename');
+      return actual.renameSync(source, destination);
+    }),
+  };
+});
+
+const fs = await import('node:fs');
+const {themeAdd} = await import('./add.mjs');
+const {listThemes} = await import('../_adapter.mjs');
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-rollback-'));
+  failures.publish = 0;
+  failures.restore = false;
+  failures.count = 0;
+});
+
+afterEach(() => {
+  failures.publish = 0;
+  failures.restore = false;
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+function stoneFiles() {
+  const theme = listThemes().find(entry => entry.slug === 'stone');
+  if (!theme) throw new Error('missing bundled theme stone');
+  expect(theme.files.length).toBeGreaterThanOrEqual(2);
+  return theme.files.map(name =>
+    path.join(tmpDir, 'src', 'themes', 'stone', name),
+  );
+}
+
+/** Entries staging or rollback left behind in the theme directory. */
+function strays() {
+  const dir = path.join(tmpDir, 'src', 'themes', 'stone');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, {recursive: true})
+    .map(String)
+    .filter(name => name.includes('.tmp') || name.includes('.restore-'));
+}
+
+describe('themeAdd rolls back a partial write', () => {
+  it('removes every created file when the second publish fails', async () => {
+    const files = stoneFiles();
+    failures.publish = 2;
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_WRITE_FAILED',
+    });
+
+    for (const file of files) expect(fs.existsSync(file)).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+
+  it('restores every replaced byte when the second publish fails', async () => {
+    const files = stoneFiles();
+    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
+    const before = Buffer.from([0x00, 0xff, 0x0a, 0x62, 0x65, 0x66]);
+    fs.writeFileSync(files[0], before);
+    failures.publish = 2;
+
+    await expect(
+      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
+    ).rejects.toMatchObject({code: 'ERR_WRITE_FAILED'});
+
+    expect(fs.readFileSync(files[0]).equals(before)).toBe(true);
+    for (const file of files.slice(1)) expect(fs.existsSync(file)).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+
+  it('names a file it could not restore', async () => {
+    const files = stoneFiles();
+    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
+    fs.writeFileSync(files[0], 'before\n');
+    failures.publish = 2;
+    failures.restore = true;
+
+    let error;
+    try {
+      await themeAdd('stone', {cwd: tmpDir, overwrite: true});
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error?.code).toBe('ERR_WRITE_FAILED');
+    expect(error?.message).toContain('Could not restore');
+    expect(error?.message).toContain(files[0]);
+  });
+
+  it('writes every file when nothing fails', async () => {
+    const files = stoneFiles();
+
+    const result = await themeAdd('stone', {cwd: tmpDir});
+
+    expect(result.type).toBe('theme.add');
+    for (const file of files) expect(fs.existsSync(file)).toBe(true);
+    expect(strays()).toEqual([]);
+  });
+});

package/api/theme/add/add.staging.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {themeAdd} from './add.mjs';
+import {listThemes} from '../_adapter.mjs';
+
+let tmpDir;
+let outsideDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-staging-'));
+  outsideDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-themeadd-outside-'),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  fs.rmSync(outsideDir, {recursive: true, force: true});
+});
+
+/**
+ * Where `theme add` writes the first file of `slug`.
+ * @param {string} slug
+ */
+function firstDestination(slug) {
+  const theme = listThemes().find(entry => entry.slug === slug);
+  if (!theme) throw new Error(`missing bundled theme ${slug}`);
+  const dest = path.join(tmpDir, 'src', 'themes', slug, theme.files[0]);
+  fs.mkdirSync(path.dirname(dest), {recursive: true});
+  return dest;
+}
+
+// Staging names are unpredictable and created exclusively, so an entry planted
+// at a predictable name beside the destination is never written through.
+describe('themeAdd staging writes stay inside the project', () => {
+  it('never writes through a link planted at a predictable staging name', async () => {
+    const victim = path.join(outsideDir, 'victim.txt');
+    fs.writeFileSync(victim, 'outside\n');
+    const dest = firstDestination('stone');
+    fs.symlinkSync(victim, `${dest}.${process.pid}.tmp`);
+
+    await themeAdd('stone', {cwd: tmpDir});
+
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
+    expect(fs.lstatSync(dest).isFile()).toBe(true);
+  });
+
+  it('never creates a file through a dangling link at a predictable staging name', async () => {
+    const victim = path.join(outsideDir, 'created.txt');
+    fs.symlinkSync(victim, `${firstDestination('stone')}.${process.pid}.tmp`);
+
+    await themeAdd('stone', {cwd: tmpDir});
+
+    expect(fs.existsSync(victim)).toBe(false);
+  });
+
+  it('refuses to replace a destination that links outside the project', async () => {
+    const victim = path.join(outsideDir, 'victim.txt');
+    fs.writeFileSync(victim, 'outside\n');
+    const dest = firstDestination('stone');
+    fs.symlinkSync(victim, dest);
+
+    await expect(
+      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
+    expect(fs.lstatSync(dest).isSymbolicLink()).toBe(true);
+  });
+
+  it('never creates a file through a dangling destination link', async () => {
+    const victim = path.join(outsideDir, 'created.txt');
+    fs.symlinkSync(victim, firstDestination('stone'));
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
+    expect(fs.existsSync(victim)).toBe(false);
+  });
+});

package/api/theme/add/add.test.mjs

@@ -30,7 +30,20 @@ describe('themeAdd (api/theme/add)', () => {
     expect(result.data.slug).toBe('neutral');
     expect(result.data.package).toBe('@astryxdesign/cli');
     expect(result.data.outputDir).toBe(path.join('src', 'themes', 'neutral'));
-    expect(result.data.files.length).toBeGreaterThan(0);
+    // Exactly what the bundle has always copied, in that order: the CLI's own
+    // descriptor stays behind.
+    expect(result.data.files).toEqual([
+      'neutralTheme.ts',
+      'icons.tsx',
+      'neutralPalettes.ts',
+      'neutralPalettes.generated.ts',
+      'neutralPaletteRefs.generated.ts',
+      'neutralPalettes.generated.receipt.json',
+      'palette.config.json',
+    ]);
+    expect(
+      fs.readdirSync(path.join(tmpDir, 'src', 'themes', 'neutral')).sort(),
+    ).toEqual([...result.data.files].sort());
     for (const f of result.data.files) {
       expect(
         fs.existsSync(path.join(tmpDir, 'src', 'themes', 'neutral', f)),

package/api/theme/build/build.family.test.mjs

@@ -251,23 +251,18 @@ describe('themeBuildFamily()', () => {
     const dir = makeDir();
     const files = writeFamily(dir);
     const outputDir = path.join(dir, 'themes');
-    const blockedTmp = path.join(
-      outputDir,
-      `${FAMILY_KEY}.js.${process.pid}.tmp`,
-    );
-    fs.mkdirSync(blockedTmp);
+    // A directory where the JS output goes fails its staging after the CSS
+    // output was already staged.
+    fs.mkdirSync(path.join(outputDir, `${FAMILY_KEY}.js`));
 
     await expect(build(dir, files)).rejects.toThrow(
       /Failed to write theme outputs/,
     );
-    for (const output of OUTPUTS) {
-      expect(fs.existsSync(path.join(outputDir, output))).toBe(false);
-    }
+    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.css`))).toBe(false);
+    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.d.ts`))).toBe(false);
     expect(
-      fs.existsSync(
-        path.join(outputDir, `${FAMILY_KEY}.css.${process.pid}.tmp`),
-      ),
-    ).toBe(false);
+      fs.readdirSync(outputDir).filter(name => name.includes('.tmp-')),
+    ).toEqual([]);
   });
 
   it('rejects invalid graphs and keys before touching an existing trio', async () => {