@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

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,