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

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);
+  });
+});