@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/api/hook/_adapter.mjs

@@ -15,7 +15,10 @@
  */
 
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
-import {findHookDoc, getAllHookNames} from '../../foundation/discovery/hook-discovery.mjs';
+import {
+  findHookDoc,
+  getAllHookNames,
+} from '../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
@@ -30,7 +33,11 @@ import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 export function resolveCoreDir(cwd) {
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
-    throw new AstryxError('Could not find @astryxdesign/core package', undefined, ERROR_CODES.ERR_CORE_NOT_FOUND);
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
   }
   return coreDir;
 }
@@ -44,7 +51,11 @@ export function resolveCoreDir(cwd) {
  * @param {{zh?: boolean, lang?: string|null}} [opts]
  * @returns {Promise<import('./hook.type.mjs').HookDoc>}
  */
-export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} = {}) {
+export async function resolveHookDoc(
+  coreDir,
+  name,
+  {zh = false, lang = null} = {},
+) {
   const docPath = findHookDoc(coreDir, name);
 
   if (!docPath) {
@@ -59,7 +70,10 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
       .filter(m => m.distance <= 5)
       .sort((a, b) => a.distance - b.distance)
       .slice(0, 5)
-      .map(m => ({name: m.name, reason: `similar name (distance ${m.distance})`}));
+      .map(m => ({
+        name: m.name,
+        reason: `similar name (distance ${m.distance})`,
+      }));
 
     throw new AstryxError(
       `No hook named "${name}"`,
@@ -68,5 +82,5 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
     );
   }
 
-  return loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+  return loadDocs(docPath, {zh, lang, root: 'hooks'});
 }

package/api/hook/hook.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'hook',
+  namespace: 'cli/api',
   displayName: 'hook()',
   summary:
     'Resolve a hook by name, or list the catalog, with an optional params-only slice.',

package/api/hook/hook.type.d.mts

@@ -4,7 +4,7 @@
 export type HookDoc = import("@astryxdesign/cli/authoring").HookDoc;
 export type HookParamDoc = import("@astryxdesign/cli/authoring").HookParamDoc;
 /**
- * xds --json hook [--list] [--category X] [--detail names|compact|full]
+ * astryx --json hook [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `hook.list` type across all three detail levels; the
  * depth is carried in `data.detail` and `data.components` holds the grouped map
@@ -39,14 +39,14 @@ export type HookBriefEntry = {
     import: string;
 };
 /**
- * xds --json hook <name>
+ * astryx --json hook <name>
  */
 export type HookDetailResponse = {
     type: "hook.detail";
     data: HookDoc;
 };
 /**
- * xds --json hook <name> --params
+ * astryx --json hook <name> --params
  */
 export type HookDetailParamsResponse = {
     type: "hook.detail.params";

package/api/hook/hook.type.mjs

@@ -11,14 +11,14 @@
  *
  * Invocation                                 -> type discriminator
  * ------------------------------------------------------------------
- * xds --json hook                           -> hook.list (data.detail='names')
- * xds --json hook --list                    -> hook.list (data.detail='names')
- * xds --json hook --category State          -> hook.list (filtered)
- * xds --json hook --list --detail compact   -> hook.list (data.detail='compact')
- * xds --json hook --list --detail full      -> hook.list (data.detail='full')
- * xds --json hook useMediaQuery             -> hook.detail
- * xds --json hook useMediaQuery --params    -> hook.detail.params
- * (not found)                               -> CLIError
+ * astryx --json hook                         -> hook.list (data.detail='names')
+ * astryx --json hook --list                  -> hook.list (data.detail='names')
+ * astryx --json hook --category State        -> hook.list (filtered)
+ * astryx --json hook --list --detail compact -> hook.list (data.detail='compact')
+ * astryx --json hook --list --detail full    -> hook.list (data.detail='full')
+ * astryx --json hook useMediaQuery           -> hook.detail
+ * astryx --json hook useMediaQuery --params  -> hook.detail.params
+ * (not found)                                -> CLIError
  */
 
 // Re-export the authored-doc types from core so the hook leaves reference these
@@ -28,7 +28,7 @@
 /** @typedef {import('@astryxdesign/cli/authoring').HookParamDoc} HookParamDoc */
 
 /**
- * xds --json hook [--list] [--category X] [--detail names|compact|full]
+ * astryx --json hook [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `hook.list` type across all three detail levels; the
  * depth is carried in `data.detail` and `data.components` holds the grouped map
@@ -56,14 +56,14 @@
  */
 
 /**
- * xds --json hook <name>
+ * astryx --json hook <name>
  * @typedef {object} HookDetailResponse
  * @property {'hook.detail'} type
  * @property {HookDoc} data
  */
 
 /**
- * xds --json hook <name> --params
+ * astryx --json hook <name> --params
  * @typedef {object} HookDetailParamsResponse
  * @property {'hook.detail.params'} type
  * @property {HookParamDoc[]} data

package/api/hook/list/list.d.mts

@@ -10,10 +10,10 @@
  * @param {string|null} [options.lang]
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
-export function list({ cwd, category, detail, zh, lang }?: {
+export function list({ cwd, category, detail, zh, lang, }?: {
     cwd?: string | undefined;
     category?: string | undefined;
-    detail?: "names" | "compact" | "full" | "brief" | undefined;
+    detail?: "compact" | "full" | "names" | "brief" | undefined;
     zh?: boolean | undefined;
     lang?: string | null | undefined;
 }): Promise<import("../hook.type.mjs").HookListResponse>;

package/api/hook/list/list.mjs

@@ -13,7 +13,10 @@
  * @position api/hook/list/list.mjs — dispatched from ../hook.mjs
  */
 
-import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -28,7 +31,13 @@ import {resolveCoreDir} from '../_adapter.mjs';
  * @param {string|null} [options.lang]
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
-export async function list({cwd = process.cwd(), category, detail = 'names', zh = false, lang = null} = {}) {
+export async function list({
+  cwd = process.cwd(),
+  category,
+  detail = 'names',
+  zh = false,
+  lang = null,
+} = {}) {
   const coreDir = resolveCoreDir(cwd);
   const hooks = discoverHooks(coreDir);
 
@@ -51,20 +60,31 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+            const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
             entries.push({
               name: hookName,
               description: docs.usage?.description || '',
               import: docs.importPath || '@astryxdesign/core/hooks',
             });
           } catch {
-            entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            entries.push({
+              name: hookName,
+              description: '',
+              import: '@astryxdesign/core/hooks',
+            });
           }
         } else {
-          entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          entries.push({
+            name: hookName,
+            description: '',
+            import: '@astryxdesign/core/hooks',
+          });
         }
       }
-      return {type: 'hook.list', data: {detail: 'compact', components: {[match[0]]: entries}}};
+      return {
+        type: 'hook.list',
+        data: {detail: 'compact', components: {[match[0]]: entries}},
+      };
     }
 
     if (detail === 'full') {
@@ -74,19 +94,33 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
+            entries.push(await loadDocs(docPath, {zh, lang, root: 'hooks'}));
           } catch {
-            entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+            entries.push(
+              /** @type {import('../hook.type.mjs').HookDoc} */ ({
+                name: hookName,
+              }),
+            );
           }
         } else {
-          entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+          entries.push(
+            /** @type {import('../hook.type.mjs').HookDoc} */ ({
+              name: hookName,
+            }),
+          );
         }
       }
-      return {type: 'hook.list', data: {detail: 'full', components: {[match[0]]: entries}}};
+      return {
+        type: 'hook.list',
+        data: {detail: 'full', components: {[match[0]]: entries}},
+      };
     }
 
     // Default: names only
-    return {type: 'hook.list', data: {detail: 'names', components: {[match[0]]: match[1]}}};
+    return {
+      type: 'hook.list',
+      data: {detail: 'names', components: {[match[0]]: match[1]}},
+    };
   }
 
   // All hooks
@@ -99,17 +133,25 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+            const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
             result[cat].push({
               name: hookName,
               description: docs.usage?.description || '',
               import: docs.importPath || '@astryxdesign/core/hooks',
             });
           } catch {
-            result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            result[cat].push({
+              name: hookName,
+              description: '',
+              import: '@astryxdesign/core/hooks',
+            });
           }
         } else {
-          result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          result[cat].push({
+            name: hookName,
+            description: '',
+            import: '@astryxdesign/core/hooks',
+          });
         }
       }
     }
@@ -125,12 +167,22 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
+            result[cat].push(
+              await loadDocs(docPath, {zh, lang, root: 'hooks'}),
+            );
           } catch {
-            result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+            result[cat].push(
+              /** @type {import('../hook.type.mjs').HookDoc} */ ({
+                name: hookName,
+              }),
+            );
           }
         } else {
-          result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+          result[cat].push(
+            /** @type {import('../hook.type.mjs').HookDoc} */ ({
+              name: hookName,
+            }),
+          );
         }
       }
     }

package/api/index.d.mts

@@ -38,7 +38,7 @@ export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
-export { themeBuild, themeAdd, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { themeBuild, themeAdd, themeTemplate, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
 export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";

package/api/index.mjs

@@ -28,6 +28,7 @@ export {template} from './template/template.mjs';
 export {
   themeBuild,
   themeAdd,
+  themeTemplate,
   themeList,
   themeListAvailable,
   themeTargets,

package/api/init/init.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'init',
+  namespace: 'cli/api',
   displayName: 'init()',
   summary:
     'Non-interactive project setup: install agent docs and point at the theme + build workflows.',
@@ -90,6 +91,10 @@ export const doc = {
       code: 'ERR_FILE_EXISTS',
       when: 'scaffolding a template would overwrite an existing page.tsx',
     },
+    {
+      code: 'ERR_PATH_TRAVERSAL',
+      when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
+    },
   ],
   examples: [
     {label: 'Default setup', code: 'const r = await init();'},
@@ -97,5 +102,5 @@ export const doc = {
     {label: 'Remove agent docs', code: 'await init({removeAgents: true});'},
   ],
   command: 'init',
-  related: ['doctor', 'upgrade', 'build', 'theme'],
+  related: ['doctor', 'upgrade', 'build', 'themeTemplate'],
 };

package/api/init/init.test.mjs

@@ -230,13 +230,40 @@ describe('init() — logger', () => {
       errSpy.mockRestore();
     }
     const text = lines.join('\n');
-    expect(text).toContain('✓ AI agent docs installed → AGENTS.md');
+    expect(text).toContain('[ok] AI agent docs installed -> AGENTS.md');
     expect(text).toContain('  Next steps:');
     // The exact next-steps block the CLI prints comes from getNextSteps().
     expect(text).toContain(getNextSteps('npx astryx')[2].slice(0, 20));
   });
 });
 
+describe('init() — ASCII output', () => {
+  it('prints only ASCII on the default, all-features, re-run, template, and remove paths', async () => {
+    /** @type {string[]} */
+    const lines = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(a.join(' ')));
+    const empty = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-remove-'));
+    logger.setSilent(false);
+    try {
+      await init({}, {cwd: tmpDir});
+      await init({all: true}, {cwd: tmpDir});
+      await init({all: true}, {cwd: tmpDir});
+      await init({features: 'template', templateName: 'blank'}, {cwd: tmpDir});
+      await init({removeAgents: true}, {cwd: tmpDir});
+      await init({removeAgents: true}, {cwd: empty});
+    } finally {
+      logger.setSilent(true);
+      logSpy.mockRestore();
+      errSpy.mockRestore();
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+    expect(lines.length).toBeGreaterThan(0);
+    expect(lines.some(line => line.startsWith('[ok] Removed'))).toBe(true);
+    expect(lines.filter(line => /[\u0080-\uFFFF]/.test(line))).toEqual([]);
+  });
+});
+
 describe('init() — write-path safety', () => {
   it('template scaffold refuses to clobber an existing page.tsx', async () => {
     const dest = path.join(tmpDir, 'src', 'pages', 'blank');
@@ -260,4 +287,17 @@ describe('init() — write-path safety', () => {
       init({features: 'template', templateName: '../../etc/evil'}, {cwd: tmpDir}),
     ).rejects.toMatchObject({code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
   });
+
+  it('refuses a template write that a symlinked src would carry outside cwd (ERR_PATH_TRAVERSAL)', async () => {
+    const outside = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-outside-'));
+    try {
+      fs.symlinkSync(outside, path.join(tmpDir, 'src'), 'dir');
+      await expect(
+        init({features: 'template', templateName: 'blank'}, {cwd: tmpDir}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+      expect(fs.readdirSync(outside)).toEqual([]);
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
 });

package/api/init/remove/remove.mjs

@@ -24,6 +24,6 @@ import {logger} from '../../logger.mjs';
  */
 export async function remove({cwd = process.cwd()} = {}) {
   removeAgentDocs(cwd);
-  logger.log('✓ AI agent docs removed.');
+  logger.log('[ok] AI agent docs removed.');
   return {type: 'init.remove', data: {removed: true}};
 }

package/api/init/run/run.mjs

@@ -17,7 +17,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
-import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {
   installAgentDocs,
@@ -98,7 +98,7 @@ async function applyAgents(cwd, options, invocation, data) {
       renderedBlock,
     });
     data.docsWritten = written;
-    logger.log(`✓ AI agent docs installed → ${written.join(', ')}`);
+    logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message — surface it
     // (and flag exit 1) instead of the generic "could not install" warning so
@@ -132,8 +132,8 @@ function applyTheme(cwd, invocation, data) {
     data.themeTemplatePath = didWrite ? written : null;
     logger.log(
       didWrite
-        ? `✓ Theme template written → ${written}`
-        : `• ${written} already exists — left as is.`,
+        ? `[ok] Theme template written -> ${written}`
+        : `- ${written} already exists - left as is.`,
     );
   } catch {
     // Soft failure, like agent docs: the guidance below is still useful.
@@ -166,16 +166,16 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
     // Point agents at the build workflow rather than dumping page-template
     // names — `build` surfaces pages AND blocks AND components for an idea,
     // and `build` with no args is the full how-to-build playbook.
-    logger.log('✓ To build UI, use these commands:');
+    logger.log('[ok] To build UI, use these commands:');
     logger.log('');
     logger.log(
-      `    ${invocation} build "<what you're building>"   build a page — kit: closest template + blocks + components`,
+      `    ${invocation} build "<what you're building>"   build a page - kit: closest template + blocks + components`,
     );
     logger.log(
       `    ${invocation} build                            the how-to-build workflow (read this first)`,
     );
     logger.log(
-      `    ${invocation} search <query>                   find anything — components, docs, templates, blocks`,
+      `    ${invocation} search <query>                   find anything - components, docs, templates, blocks`,
     );
     logger.log('');
     data.template = 'workflow';
@@ -190,9 +190,19 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
     );
   }
 
-  const outputDir = path.resolve(cwd, `./src/pages/${templateName}`);
+  let destFile;
+  try {
+    destFile = assertWithin(path.join('src', 'pages', templateName, 'page.tsx'), cwd, {
+      label: 'template output path',
+    });
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+  const outputDir = path.dirname(destFile);
   const srcPath = path.join(CLI_ROOT, 'assets', 'templates', 'pages', templateName, 'page.tsx');
-  const destFile = path.join(outputDir, 'page.tsx');
   // Don't clobber a user's existing page — same guard the peer template/copy and
   // theme/add write-leaves apply (init is a public API surface too).
   if (fs.existsSync(destFile)) {
@@ -206,7 +216,7 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
   fs.mkdirSync(outputDir, {recursive: true});
   fs.copyFileSync(srcPath, destFile);
   const rel = path.relative(cwd, outputDir);
-  logger.log(`✓ Template created at ${rel}/page.tsx`);
+  logger.log(`[ok] Template created at ${rel}/page.tsx`);
   data.template = 'created';
   data.templatePath = rel;
 }

package/api/integration/add-contribution.component-names.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {integrationAdd, integrationAddComponent} from './add-contribution.mjs';
+import {discoverIntegrationComponents} from '../../foundation/discovery/component-discovery.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-add-component-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist']}, null, 2)}\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {\n  components: './components',\n};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} relativeDoc */
+function writeAuthoredComponent(relativeDoc) {
+  const doc = path.join(tmpDir, relativeDoc);
+  fs.mkdirSync(path.dirname(doc), {recursive: true});
+  fs.writeFileSync(
+    doc,
+    "export default {\n  type: 'component',\n  name: 'AcmeWidget',\n  description: 'The authored AcmeWidget.',\n  props: [],\n};\n",
+  );
+  fs.writeFileSync(
+    doc.replace(/\.doc\.(?:ts|mjs|js)$/u, '.tsx'),
+    'export function AcmeWidget() {\n  return <div>Authored</div>;\n}\n',
+  );
+}
+
+/** Every file under the package, with its bytes. */
+function snapshot() {
+  /** @type {Record<string, string>} */
+  const files = {};
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else files[path.relative(tmpDir, full)] = fs.readFileSync(full, 'utf-8');
+    }
+  };
+  walk(tmpDir);
+  return files;
+}
+
+describe('integrationAddComponent name collisions', () => {
+  it('refuses a name a nested component doc already defines', async () => {
+    writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
+    const before = snapshot();
+
+    await expect(
+      integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_FILE_EXISTS',
+      message: expect.stringContaining(
+        'components/AcmeWidget/AcmeWidget.doc.mjs',
+      ),
+    });
+    expect(snapshot()).toEqual(before);
+    expect(
+      discoverIntegrationComponents({
+        name: '@acme/widgets',
+        components: path.join(tmpDir, 'components'),
+      }).map(component => path.relative(tmpDir, component.docPath)),
+    ).toEqual([path.join('components', 'AcmeWidget', 'AcmeWidget.doc.mjs')]);
+  });
+
+  it('refuses the same collision under --dry-run', async () => {
+    writeAuthoredComponent('components/widgets/AcmeWidget.doc.mjs');
+
+    await expect(
+      integrationAdd('component', 'AcmeWidget', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+  });
+
+  it('refuses a same-stem doc with another extension in the root', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.doc.ts'),
+      "export default {type: 'component', name: 'AcmeWidget', props: []};\n",
+    );
+    const before = snapshot();
+
+    await expect(
+      integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+    expect(snapshot()).toEqual(before);
+  });
+
+  it('still adds a component whose name is free', async () => {
+    writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
+
+    const result = await integrationAddComponent('AcmeBadge', {cwd: tmpDir});
+
+    expect(result.data.files).toEqual([
+      'components/AcmeBadge.doc.mjs',
+      'components/AcmeBadge.tsx',
+      'package.json',
+    ]);
+    expect(
+      discoverIntegrationComponents({
+        name: '@acme/widgets',
+        components: path.join(tmpDir, 'components'),
+      })
+        .map(component => component.name)
+        .sort(),
+    ).toEqual(['AcmeBadge', 'AcmeWidget']);
+  });
+});

package/api/integration/add-contribution.d.mts

@@ -31,7 +31,7 @@ export function integrationAddAgentDoc(line: string, options?: import("./integra
  *
  * @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
  * @param {string} name
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string}} [options]
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
  */
 export function integrationAdd(kind: "component" | "doc" | "template" | "codemod" | "agent-doc" | "theme", name: string, options?: {
@@ -41,4 +41,5 @@ export function integrationAdd(kind: "component" | "doc" | "template" | "codemod
     to?: string;
     replaces?: string;
     extends?: string;
+    parent?: string;
 }): Promise<import("./integration-authoring.type.mjs").IntegrationAddResponse>;