@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.dea6813

package/api/layout/expand/expand.path-safety.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety tests for the `layout.expand` write. The file written, not
+ * only the directory it lands in, must stay inside the project root.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {layoutExpand} from '../layout.mjs';
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+
+const SLOW = 30_000;
+
+// The registry imports every component doc on first use; warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+describe('layout.expand — write confinement', () => {
+  it('rejects a directory target whose generated file is a symlink leading outside cwd', async () => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'xle-confine-outside-'));
+    try {
+      const victim = path.join(outside, 'victim.tsx');
+      fs.writeFileSync(victim, 'OUTSIDE');
+      fs.mkdirSync(path.join(cwd, 'out'));
+      fs.symlinkSync(victim, path.join(cwd, 'out', 'GeneratedLayout.tsx'));
+
+      await expect(
+        layoutExpand('V > B', {targetPath: './out', cwd}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(victim, 'utf-8')).toBe('OUTSIDE');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('still writes <Name>.tsx into a plain directory target', async () => {
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    try {
+      const result = await layoutExpand('V > B', {targetPath: './out', name: 'Demo', cwd});
+      expect(result.data.written).toBe(path.join('out', 'Demo.tsx'));
+      expect(fs.existsSync(path.join(cwd, 'out', 'Demo.tsx'))).toBe(true);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/layout/grammar/grammar.mjs

@@ -10,6 +10,7 @@
  */
 
 import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+import {MAX_REPEAT} from '../../../foundation/xle/expand.mjs';
 
 /**
  * `astryx layout grammar` — the agent cheatsheet, with the alias table
@@ -50,7 +51,7 @@ NODE ANATOMY   Name#id.enum"payload"[attrs]{hint}*N > children
   .enum        unique enum value of any prop:  Bd.success  Tx.lg  B.primary
   "payload"    primary text prop (label/title/heading) or text child:  TI"Email"  B"Save"
   {hint}       kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
-  *N / xN      repeat (use $ for the counter:  Tk"item-$"*3)
+  *N / xN      repeat, at most ${MAX_REPEAT} copies (use $ for the counter:  Tk"item-$"*3)
   trailing !   initial selection for scaffolded state:  Tab"Overview"!
 
 ATTRS [...] (outline: bare tokens after the name, no brackets)

package/api/layout/layoutExpand.doc.mjs

@@ -36,7 +36,7 @@ export const doc = {
       name: 'options.targetPath',
       type: 'string',
       description:
-        'Write the generated TSX here (validated to stay within cwd). A directory gets <name>.tsx; a file path is used as-is. Omit to return the code without writing.',
+        'Write the generated TSX here (validated to stay within cwd). A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is used as-is; any other path is a directory that gets <name>.tsx. An existing file is replaced. Omit to return the code without writing.',
     },
     {
       name: 'options.form',

package/api/search/search-return-type.test.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The declared return type of `search()` is the canonical SearchResponse.
+ * Consumers of `@astryxdesign/cli/api` type-check against it; an `object` entry
+ * type erases every result field from their view.
+ */
+
+import {createRequire} from 'node:module';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+const require = createRequire(import.meta.url);
+const ts = require('typescript');
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SEARCH = path.join(HERE, 'search.mjs');
+const TYPES = path.join(HERE, 'search.type.mjs');
+
+describe('search() declared return type', () => {
+  it('types each result as the canonical SearchResultEntry', () => {
+    const program = ts.createProgram([SEARCH, TYPES], {
+      allowJs: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ES2022,
+    });
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(SEARCH);
+    /** @param {string} file @param {string} name */
+    const exportOf = (file, name) =>
+      checker
+        .getExportsOfModule(checker.getSymbolAtLocation(program.getSourceFile(file)))
+        .find((/** @type {any} */ s) => s.name === name);
+    /** @param {any} type @param {string} name */
+    const prop = (type, name) =>
+      checker.getTypeOfSymbolAtLocation(type.getProperty(name), source);
+    /** @param {any} type */
+    const names = type => type.getProperties().map((/** @type {any} */ p) => p.name).sort();
+
+    const fn = checker.getTypeOfSymbolAtLocation(exportOf(SEARCH, 'search'), source);
+    const response = checker.getAwaitedType(fn.getCallSignatures()[0].getReturnType());
+    const data = prop(response, 'data');
+    expect(names(data)).toEqual(['matchCount', 'query', 'results']);
+    const entry = checker.getIndexTypeOfType(prop(data, 'results'), ts.IndexKind.Number);
+    const canonical = checker.getDeclaredTypeOfSymbol(exportOf(TYPES, 'SearchResultEntry'));
+    expect(names(canonical)).toContain('command');
+    expect(names(entry)).toEqual(names(canonical));
+  }, 30_000);
+});

package/api/search/search.d.mts

@@ -68,20 +68,13 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
     type?: "component" | "hook" | "doc" | "template" | undefined;
     limit?: number | undefined;
-}): Promise<{
-    type: "search";
-    data: {
-        query: string;
-        matchCount: number;
-        results: Array<object>;
-    };
-}>;
+}): Promise<import("./search.type.mjs").SearchResponse>;
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS: string[];
 /**

package/api/search/search.doc.mjs

@@ -53,7 +53,7 @@ export const doc = {
     {
       type: 'search',
       description:
-        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, and `displayName` and `kind` for templates.',
     },
   ],
   throws: [
@@ -61,6 +61,10 @@ export const doc = {
       code: 'ERR_INVALID_ARGUMENT',
       when: 'the query is empty, --type is unknown, or --limit is not a positive integer',
     },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: '@astryxdesign/core cannot be found from the cwd',
+    },
   ],
   examples: [
     {label: 'Find a component', code: "const r = await search('button');"},

package/api/search/search.mjs

@@ -884,7 +884,7 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export async function search(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 20} = options;
@@ -921,7 +921,11 @@ export async function search(query, options = {}) {
 
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
-    throw new AstryxError('Could not find @astryxdesign/core package');
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
   }
 
   // Gather candidates from each requested domain in parallel.
@@ -971,7 +975,10 @@ export async function search(query, options = {}) {
     data: {
       query: String(query).trim(),
       matchCount: scored.length,
-      results: limited,
+      // toResult gives every domain its command and domain fields.
+      results: /** @type {import('./search.type.mjs').SearchResultEntry[]} */ (
+        limited
+      ),
     },
   };
 }

package/api/search/search.test.mjs

@@ -21,6 +21,7 @@
 
 import {describe, it, expect} from 'vitest';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {
@@ -70,6 +71,28 @@ describe('search leaf — envelope + ranking', () => {
   }, SLOW);
 });
 
+describe('search leaf — per-domain result fields', () => {
+  it('carries import for components and hooks, title for docs, displayName and kind for templates', async () => {
+    const r = await search('theme', {cwd, limit: 60});
+    expect(new Set(r.data.results.map(res => res.domain))).toEqual(
+      new Set(SEARCH_DOMAINS),
+    );
+    for (const res of r.data.results) {
+      expect(typeof res.command).toBe('string');
+      expect(typeof res.description).toBe('string');
+      if (res.domain === 'component' || res.domain === 'hook') {
+        expect(res.import).toMatch(/\S/);
+      } else if (res.domain === 'doc') {
+        expect(res.title).toMatch(/\S/);
+        expect(res.command).toBe(`astryx docs ${res.name}`);
+      } else {
+        expect(res.displayName).toMatch(/\S/);
+        expect(['page', 'block']).toContain(res.kind);
+      }
+    }
+  }, SLOW);
+});
+
 describe('search leaf — matchCount is the total, not the cap', () => {
   it('reports every match while `results` stays bounded by the limit', async () => {
     // The regression: `matchCount` used to be `results.length`, so a query
@@ -160,6 +183,17 @@ describe('search leaf — error paths (pinned)', () => {
       search('button', {cwd, type: /** @type {any} */ ('bogus')}),
     ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
   }, SLOW);
+
+  it('throws ERR_CORE_NOT_FOUND when @astryxdesign/core cannot be found', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-no-core-'));
+    try {
+      await expect(search('button', {cwd: empty})).rejects.toMatchObject({
+        code: 'ERR_CORE_NOT_FOUND',
+      });
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  }, SLOW);
 });
 
 describe('search leaf — limit validation (API matches the CLI contract)', () => {

package/api/swizzle/copy/copy.mjs

@@ -159,6 +159,24 @@ function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
   return owners;
 }
 
+/**
+ * `assertWithin`, with an escape reported as ERR_PATH_TRAVERSAL.
+ * @param {string} target
+ * @param {string} cwd
+ * @param {{allowAbsolute?: boolean, label: string}} options
+ * @returns {string}
+ */
+function confineWrite(target, cwd, options) {
+  try {
+    return assertWithin(target, cwd, options);
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, [], ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+}
+
 /** @param {string} file */
 function isExcludedFromCopy(file) {
   return (
@@ -243,23 +261,22 @@ export async function swizzleCopy(component, options = {}) {
 
   const componentDir = owner.sourceDir;
 
-  // Path-safety: --output must resolve inside cwd.
-  let outputBase;
-  try {
-    outputBase = assertWithin(output, cwd, {label: 'output directory'});
-  } catch (err) {
-    if (err instanceof PathSafetyError) {
-      throw new AstryxError(err.message, [], ERROR_CODES.ERR_PATH_TRAVERSAL);
-    }
-    throw err;
-  }
+  // Path-safety: every write target resolves inside cwd, not just --output. An
+  // existing component directory or file may be a symlink out of cwd.
+  const outputBase = confineWrite(output, cwd, {label: 'output directory'});
   const outputDir = path.join(outputBase, dirName);
 
-  // Pre-flight overwrite check before any mkdir/writeFile.
+  // Pre-flight path and overwrite checks before any mkdir/writeFile.
   const sourceFiles = fs.readdirSync(componentDir).filter(file => {
     if (isExcludedFromCopy(file)) return false;
     return fs.statSync(path.join(componentDir, file)).isFile();
   });
+  for (const file of sourceFiles) {
+    confineWrite(path.join(outputDir, file), cwd, {
+      allowAbsolute: true,
+      label: 'output file',
+    });
+  }
   const existingFiles = sourceFiles.filter(f =>
     fs.existsSync(path.join(outputDir, f)),
   );

package/api/swizzle/swizzle.doc.mjs

@@ -80,7 +80,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the component name contains a path separator or traversal, or output resolves outside cwd',
+      when: 'the component name contains a path separator or traversal, output resolves outside cwd, or an existing output file or directory is a symlink that resolves outside cwd',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',

package/api/template/copy/copy.mjs

@@ -36,13 +36,22 @@ export function templateCopy(match, {targetPath, cwd, overwrite = false}) {
     );
   }
 
-  // Path-safety: resolve the user-supplied targetPath relative to cwd,
-  // rejecting absolute paths and any traversal that escapes the project
-  // root. This guard runs BEFORE any mkdir/copyFile so we never create
-  // directories outside the root just to fail on the file write.
-  let resolvedTarget;
+  // If targetPath looks like a file (e.g. `./foo.tsx`), write directly to
+  // it. Previously this path was treated as a directory and the file was
+  // written as `./foo.tsx/page.tsx`, which is wrong and surprising.
+  const fileTarget = isFilePathArg(targetPath)
+    ? targetPath
+    : path.join(
+        targetPath,
+        match.type === 'block' ? path.basename(match.filePath) : 'page.tsx',
+      );
+
+  // Path-safety: the guard sees the file that will be written, not only its
+  // directory — a symlink at that name would otherwise carry the write
+  // outside the project root. Runs BEFORE any mkdir/write.
+  let outputFilePath;
   try {
-    resolvedTarget = assertWithin(targetPath, cwd, {
+    outputFilePath = assertWithin(fileTarget, cwd, {
       label: 'template target path',
     });
   } catch (err) {
@@ -55,23 +64,8 @@ export function templateCopy(match, {targetPath, cwd, overwrite = false}) {
     }
     throw err;
   }
-
-  // If targetPath looks like a file (e.g. `./foo.tsx`), write directly to
-  // it. Previously this path was treated as a directory and the file was
-  // written as `./foo.tsx/page.tsx`, which is wrong and surprising.
-  let outputDir;
-  let outputFileName;
-  let outputFilePath;
-  if (isFilePathArg(targetPath)) {
-    outputDir = path.dirname(resolvedTarget);
-    outputFileName = path.basename(resolvedTarget);
-    outputFilePath = resolvedTarget;
-  } else {
-    outputDir = resolvedTarget;
-    outputFileName =
-      match.type === 'block' ? path.basename(match.filePath) : 'page.tsx';
-    outputFilePath = path.join(outputDir, outputFileName);
-  }
+  const outputDir = path.dirname(outputFilePath);
+  const outputFileName = path.basename(outputFilePath);
 
   // Refuse to clobber an existing file unless the caller opts in. The CLI has
   // its own pre-flight collision message, but the API is a public surface

package/api/template/copy/copy.test.mjs

@@ -48,4 +48,21 @@ describe('template.copy — overwrite + path safety', () => {
     ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
     expect(fs.existsSync(path.join(dir, '..', 'escape.tsx'))).toBe(false);
   }, SLOW);
+
+  it('rejects a directory target whose page.tsx is a symlink leading outside cwd', async () => {
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'tmpl-copy-outside-'));
+    try {
+      const victim = path.join(outside, 'victim.tsx');
+      fs.writeFileSync(victim, 'OUTSIDE');
+      fs.mkdirSync(path.join(dir, 'dest'));
+      fs.symlinkSync(victim, path.join(dir, 'dest', 'page.tsx'));
+
+      await expect(
+        template('blank', {targetPath: './dest', overwrite: true, cwd: dir}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(victim, 'utf-8')).toBe('OUTSIDE');
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  }, SLOW);
 });

package/api/template/template.doc.mjs

@@ -75,7 +75,8 @@ export const doc = {
       name: 'options.targetPath',
       type: 'string',
       description:
-        'Destination (relative to cwd) to scaffold the template into. Its presence switches a named lookup into a copy.',
+        'Destination (relative to cwd) to scaffold the template into. Its presence switches a named lookup into a copy. ' +
+        'A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; any other path is a directory, which receives page.tsx for a page template or the block\'s own file name for a block.',
     },
     {
       name: 'options.overwrite',

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

@@ -0,0 +1,91 @@
+// 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';
+
+const HEADER = '// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n';
+
+let tmpDir;
+
+/** Every byte value, so any lossy text decoding shows up as a changed file. */
+const FONT_BYTES = Buffer.concat([
+  Buffer.from('wOF2'),
+  Buffer.from(Array.from({length: 256}, (_, byte) => byte)),
+]);
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-binary-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({
+      name: 'consumer',
+      dependencies: {'@acme/themes': '^1.0.0'},
+    }),
+  );
+  const packageDir = path.join(tmpDir, 'node_modules', '@acme', 'themes');
+  const themeDir = path.join(packageDir, 'themes', 'ocean');
+  fs.mkdirSync(path.join(themeDir, 'fonts'), {recursive: true});
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({name: '@acme/themes', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(packageDir, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  fs.writeFileSync(
+    path.join(packageDir, 'themes', 'manifest.json'),
+    JSON.stringify({
+      version: 1,
+      themes: [
+        {
+          slug: 'ocean',
+          displayName: 'Ocean',
+          description: 'Integration theme that ships a font.',
+          maintained: true,
+          entry: 'oceanTheme.ts',
+          exportName: 'oceanTheme',
+          files: ['oceanTheme.ts', 'fonts/ocean.woff2'],
+        },
+      ],
+    }),
+  );
+  fs.writeFileSync(
+    path.join(themeDir, 'oceanTheme.ts'),
+    `${HEADER}export const oceanTheme = {};\n`,
+  );
+  fs.writeFileSync(path.join(themeDir, 'fonts', 'ocean.woff2'), FONT_BYTES);
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('themeAdd copies every listed file', () => {
+  it('copies a binary file byte for byte', async () => {
+    const result = await themeAdd('ocean', {
+      cwd: tmpDir,
+      package: '@acme/themes',
+    });
+
+    expect(result.data.files).toEqual(['oceanTheme.ts', 'fonts/ocean.woff2']);
+    const copied = fs.readFileSync(
+      path.join(tmpDir, 'src', 'themes', 'ocean', 'fonts', 'ocean.woff2'),
+    );
+    expect(copied.equals(FONT_BYTES)).toBe(true);
+  });
+
+  it('still strips the repo header from a text source', async () => {
+    await themeAdd('ocean', {cwd: tmpDir, package: '@acme/themes'});
+
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'oceanTheme.ts'),
+        'utf-8',
+      ),
+    ).toBe('export const oceanTheme = {};\n');
+  });
+});

package/api/theme/add/add.mjs

@@ -26,6 +26,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
@@ -134,9 +148,12 @@ export async function themeAdd(slug, options = {}) {
         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);
+      // The staging file is an output path too: confine it, and never write
+      // through an entry that already exists under its name.
+      const tmp = assertWithin(`${w.name}.${process.pid}.tmp`, resolvedDir, {
+        label: `theme staging file for ${w.name}`,
+      });
+      fs.writeFileSync(tmp, scaffoldContents(fs.readFileSync(w.src)), {flag: 'wx'});
       staged.push({tmp, dest});
     }
     for (const s of staged) {

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

@@ -0,0 +1,66 @@
+// 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';
+import {isErrorCode} from '../../../foundation/response/error-codes.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});
+});
+
+/**
+ * Put a symlink where `theme add` stages the first file of `slug`.
+ * @param {string} slug
+ * @param {string} target
+ */
+function plantStagingLink(slug, target) {
+  const theme = listThemes().find(entry => entry.slug === slug);
+  if (!theme) throw new Error(`missing bundled theme ${slug}`);
+  const first = theme.files[0];
+  const dest = path.join(tmpDir, 'src', 'themes', slug, first);
+  fs.mkdirSync(path.dirname(dest), {recursive: true});
+  fs.symlinkSync(target, `${dest}.${process.pid}.tmp`);
+  return dest;
+}
+
+describe('themeAdd staging writes stay inside the project', () => {
+  it('refuses a staging path that links outside the project', async () => {
+    const victim = path.join(outsideDir, 'victim.txt');
+    fs.writeFileSync(victim, 'outside\n');
+    const dest = plantStagingLink('stone', victim);
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
+    expect(fs.existsSync(dest)).toBe(false);
+  });
+
+  it('never creates a file through a dangling staging link', async () => {
+    const victim = path.join(outsideDir, 'created.txt');
+    plantStagingLink('stone', victim);
+
+    let error;
+    try {
+      await themeAdd('stone', {cwd: tmpDir});
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(isErrorCode(error?.code)).toBe(true);
+    expect(fs.existsSync(victim)).toBe(false);
+  });
+});