@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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:
@@ -28,17 +29,19 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        'Bare or XDS-prefixed component name to copy. Omit to list the swizzlable components.',
+        "Component name to copy (e.g. 'Button'). Omit to list the swizzlable components.",
     },
     {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.output',
       type: 'string',
-      description: 'Output directory; must resolve inside cwd.',
+      description:
+        'Output directory, relative to cwd. An absolute path, or one that resolves outside cwd, throws ERR_PATH_TRAVERSAL.',
       default: "'./components/astryx'",
     },
     {
@@ -70,7 +73,7 @@ export const doc = {
     {
       type: 'swizzle.copy',
       description:
-        'A receipt after copying the component into the project: the component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer-feedback note.',
+        'A receipt after copying the component into the project: the component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
     },
   ],
   throws: [
@@ -80,7 +83,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 is absolute or resolves outside cwd, or an existing output file or directory is a symlink that resolves outside cwd',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
@@ -107,7 +110,7 @@ export const doc = {
     {label: 'Eject a component', code: "await swizzle('Button');"},
     {
       label: 'Disambiguate by package',
-      code: "await swizzle('Button', {package: '@astryxdesign/core'});",
+      code: "await swizzle('Button', {package: '@astryxdesign/core', overwrite: true});",
     },
     {
       label: 'Custom output directory',

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
@@ -80,7 +74,7 @@ export function templateCopy(match, {targetPath, cwd, overwrite = false}) {
   if (!overwrite && fs.existsSync(outputFilePath)) {
     const rel = path.relative(cwd, outputFilePath) || outputFilePath;
     throw new AstryxError(
-      `Refusing to overwrite existing file ${rel}. Re-run with overwrite to replace it.`,
+      `Refusing to overwrite existing file ${rel}. Re-run with --overwrite (or -f) to replace it.`,
       undefined,
       ERROR_CODES.ERR_FILE_EXISTS,
     );

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

@@ -35,6 +35,15 @@ describe('template.copy — overwrite + path safety', () => {
     expect(fs.readFileSync(path.join(dir, 'mine.tsx'), 'utf-8')).toBe('USER CODE');
   }, SLOW);
 
+  it('names the flag that replaces the file, as swizzle and theme add do', async () => {
+    fs.writeFileSync(path.join(dir, 'mine.tsx'), 'USER CODE');
+    await expect(
+      template('blank', {targetPath: './mine.tsx', cwd: dir}),
+    ).rejects.toThrow(
+      'Refusing to overwrite existing file mine.tsx. Re-run with --overwrite (or -f) to replace it.',
+    );
+  }, SLOW);
+
   it('overwrites when overwrite:true is passed', async () => {
     fs.writeFileSync(path.join(dir, 'mine.tsx'), 'USER CODE');
     const res = await template('blank', {targetPath: './mine.tsx', overwrite: true, cwd: dir});
@@ -48,4 +57,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)}",
+    );
+  });
+});