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

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,129 @@ 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/);
+        const read = `astryx docs ${res.name}`;
+        expect([read, `${read} --index`, `${read} ${res.section}`]).toContain(res.command);
+      } else {
+        expect(res.displayName).toMatch(/\S/);
+        expect(['page', 'block']).toContain(res.kind);
+      }
+    }
+  }, SLOW);
+});
+
+describe('search leaf — docs at the grain a reader reads them', () => {
+  it(
+    'finds one section of a guide, and a docs-tree leaf by its own name',
+    async () => {
+      const guide = await search('codemod protected files', {cwd, type: 'doc'});
+      expect(guide.data.results.slice(0, 3)).toContainEqual(
+        expect.objectContaining({
+          domain: 'doc',
+          name: 'cli/integrations',
+          section: 'codemods',
+          title: 'Astryx CLI › CLI Integrations › Codemods',
+          parent: 'astryx docs cli/integrations --index',
+          command: 'astryx docs cli/integrations codemods',
+        }),
+      );
+      const block = await search('token-ref', {cwd});
+      expect(block.data.results[0]).toMatchObject({
+        name: 'authoring',
+        section: 'reference-doc',
+        command: 'astryx docs authoring reference-doc',
+      });
+      const fn = await search('assertResponse', {cwd, type: 'doc'});
+      expect(fn.data.results[0]).toMatchObject({
+        name: 'cli/api/functions/assert-response',
+        title: 'Astryx CLI › API › Functions › assertResponse()',
+        parent: 'astryx docs cli/api/functions',
+        command: 'astryx docs cli/api/functions/assert-response',
+      });
+      expect(fn.data.results[0]).not.toHaveProperty('section');
+    },
+    SLOW,
+  );
+
+  it(
+    'finds the component batch guide from task language',
+    async () => {
+      const result = await search('look up several components', {
+        cwd,
+        type: 'doc',
+      });
+      expect(result.data.results).toContainEqual(
+        expect.objectContaining({
+          name: 'cli/component-lookups',
+          section: 'several',
+          command: 'astryx docs cli/component-lookups several',
+        }),
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'gives a top-level namespace hit the topic list as its parent',
+    async () => {
+      for (const [query, route] of [['unorganized', 'unorganized'], ['Astryx CLI', 'cli']]) {
+        const r = await search(query, {cwd, type: 'doc'});
+        expect(r.data.results).toContainEqual(
+          expect.objectContaining({
+            name: route,
+            command: `astryx docs ${route}`,
+            parent: 'astryx docs',
+          }),
+        );
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'points a topic hit at its index, never a whole-topic read',
+    async () => {
+      const r = await search('cli/integrations', {cwd, type: 'doc'});
+      expect(r.data.results[0]).toMatchObject({
+        name: 'cli/integrations',
+        command: 'astryx docs cli/integrations --index',
+      });
+      expect(r.data.results[0]).not.toHaveProperty('section');
+    },
+    SLOW,
+  );
+
+  it(
+    'searches docs where @astryxdesign/core is not installed',
+    async () => {
+      const bare = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'astryx-search-bare-'),
+      );
+      try {
+        const r = await search('assertResponse', {cwd: bare, type: 'doc'});
+        expect(r.data.results[0].name).toBe(
+          'cli/api/functions/assert-response',
+        );
+      } finally {
+        fs.rmSync(bare, {recursive: true, force: true});
+      }
+    },
+    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 +284,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)', () => {
@@ -213,12 +348,18 @@ describe('search leaf — integration components', () => {
     );
     fs.writeFileSync(
       path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),
-      `export const docs = {
+      `export default {
+        type: 'component',
         name: 'FancyGizmo',
         keywords: ['gizmo', 'widget'],
         usage: {description: 'A fancy gizmo widget.'},
+        props: [],
       };\n`,
     );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'components', 'FancyGizmo.tsx'),
+      `export function FancyGizmo() { return null; }\n`,
+    );
 
     return dir;
   }

package/api/search/search.type.d.mts

@@ -14,7 +14,7 @@ export type SearchResultEntry = {
      */
     domain: SearchDomain;
     /**
-     * - Primary identifier (component/hook name, doc topic, template dir).
+     * - Primary identifier (component/hook name, doc topic or docs-tree route, template dir).
      */
     name: string;
     /**
@@ -41,6 +41,18 @@ export type SearchResultEntry = {
      * - Doc title — present for doc results.
      */
     title?: string | undefined;
+    /**
+     * - Section key — present when a doc result is one section of a topic; `command` reads only that section.
+     */
+    section?: string | undefined;
+    /**
+     * - The npm package that authored a doc result; for a section, the package whose file the section came from.
+     */
+    package?: string | undefined;
+    /**
+     * - Command that opens the level above a doc result — its topic's section list for a section, the docs-tree namespace it sits in for a tree node — so a reader can see the siblings and open another.
+     */
+    parent?: string | undefined;
     /**
      * - Friendly display name — present for template results.
      */
@@ -48,10 +60,10 @@ export type SearchResultEntry = {
     /**
      * - Template kind (`page` | `block`) — present for template results.
      */
-    kind?: "block" | "page" | undefined;
+    kind?: "page" | "block" | undefined;
 };
 /**
- * xds --json search <query>
+ * astryx --json search <query>
  */
 export type SearchResponse = {
     type: "search";

package/api/search/search.type.mjs

@@ -16,19 +16,22 @@
  * A single ranked search result, tagged with its domain.
  * @typedef {object} SearchResultEntry
  * @property {SearchDomain} domain - Which content domain this result came from.
- * @property {string} name - Primary identifier (component/hook name, doc topic, template dir).
+ * @property {string} name - Primary identifier (component/hook name, doc topic or docs-tree route, template dir).
  * @property {number} score - Relevance score (higher is better).
  * @property {string} reason - Human-readable reason the candidate matched (e.g. `keyword "button"`).
  * @property {string} description - One-line description, when available.
  * @property {string} command - Follow-up command to act on this result (e.g. `astryx component Button`).
  * @property {string} [import] - Import path — present for component and hook results.
  * @property {string} [title] - Doc title — present for doc results.
+ * @property {string} [section] - Section key — present when a doc result is one section of a topic; `command` reads only that section.
+ * @property {string} [package] - The npm package that authored a doc result; for a section, the package whose file the section came from.
+ * @property {string} [parent] - Command that opens the level above a doc result — its topic's section list for a section, the docs-tree namespace it sits in for a tree node — so a reader can see the siblings and open another.
  * @property {string} [displayName] - Friendly display name — present for template results.
  * @property {'page' | 'block'} [kind] - Template kind (`page` | `block`) — present for template results.
  */
 
 /**
- * xds --json search <query>
+ * astryx --json search <query>
  * @typedef {object} SearchResponse
  * @property {'search'} type
  * @property {object} data

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

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'swizzle',
+  namespace: 'cli/api',
   displayName: 'swizzle()',
   summary: "Eject a component's source into your project for customization.",
   description:
@@ -80,7 +81,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/swizzle/swizzle.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json swizzle [--list]
+ * astryx --json swizzle [--list]
  */
 export type SwizzleListResponse = {
     type: "swizzle.list";
@@ -22,7 +22,7 @@ export type SwizzleFeedback = {
     ghCommand?: string | undefined;
 };
 /**
- * xds --json swizzle <component>
+ * astryx --json swizzle <component>
  */
 export type SwizzleCopyResponse = {
     type: "swizzle.copy";

package/api/swizzle/swizzle.type.mjs

@@ -7,7 +7,7 @@
  */
 
 /**
- * xds --json swizzle [--list]
+ * astryx --json swizzle [--list]
  *
  * @typedef {object} SwizzleListResponse
  * @property {'swizzle.list'} type
@@ -23,7 +23,7 @@
  */
 
 /**
- * xds --json swizzle <component>
+ * astryx --json swizzle <component>
  *
  * @typedef {object} SwizzleCopyResponse
  * @property {'swizzle.copy'} type

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/list/list.mjs

@@ -32,6 +32,7 @@ export function templateList(templates, options = {}) {
       description: t.description,
       type: t.type,
       package: pkgOf(t),
+      replaces: t.replaces,
       category: t.category || undefined,
       componentsUsed: t.componentsUsed ?? undefined,
       aspectRatio: t.aspectRatio,

package/api/template/table-floating-bulk-actions.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression coverage for the floating bulk-actions Table block.
+ * @input The shipped TableFloatingBulkActionsTable source.
+ * @output Assertions for width, logical scrolling, local stacking, and shared toolbar geometry.
+ * @position Template contract test for the website example layout.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+const sourcePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../assets/templates/blocks/components/Table/TableFloatingBulkActionsTable.tsx',
+);
+const source = fs.readFileSync(sourcePath, 'utf8');
+const pageStyles = source.match(/page:\s*\{([\s\S]*?)\n\s{2}\},/)?.[1];
+const tableRegionStyles = source.match(
+  /tableRegion:\s*\{([\s\S]*?)\n\s{2}\},/,
+)?.[1];
+const toolbarStyles = source.match(/toolbar:\s*\{([\s\S]*?)\n\s{2}\},/)?.[1];
+const columns = source.match(
+  /const columns:[\s\S]*?=\s*\[([\s\S]*?)\n\];/,
+)?.[1];
+
+describe('Table floating bulk-actions template', () => {
+  it('caps the demo height without capping its width', () => {
+    expect(pageStyles).toContain('maxBlockSize: 640');
+    expect(pageStyles).not.toContain('maxWidth');
+    expect(pageStyles).not.toContain('marginInline');
+  });
+
+  it('uses the shared logical-axis scroll behavior', () => {
+    expect(source).toContain(
+      "import {ScrollableArea} from '@astryxdesign/core/ScrollableArea'",
+    );
+    expect(source).toMatch(
+      /<ScrollableArea[\s\S]*?axis="block"[\s\S]*?label="Bulk actions example"[\s\S]*?overscroll="contain"/,
+    );
+    expect(source).not.toContain('role="region"');
+    expect(source).not.toContain('tabIndex={0}');
+    expect(source).not.toContain('aria-label="Metrics"');
+    expect(pageStyles).not.toContain('overflowY');
+    expect(pageStyles).not.toContain('overscrollBehavior');
+  });
+
+  it('keeps the floating toolbar inside an isolated local stacking context', () => {
+    expect(pageStyles).toContain("isolation: 'isolate'");
+    expect(toolbarStyles).toContain('zIndex: 1');
+    expect(toolbarStyles).not.toContain('zIndex: 20');
+  });
+
+  it('shares one reserved-space variable across the placement geometry', () => {
+    expect(tableRegionStyles).toContain("'--table-bulk-actions-space'");
+    expect(source.match(/var\(--table-bulk-actions-space\)/g)).toHaveLength(4);
+  });
+
+  it('keeps the email column compact enough to avoid horizontal overflow', () => {
+    expect(columns).toContain(
+      "{key: 'email', header: 'Email', width: proportional(1)}",
+    );
+  });
+});