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

package/api/component/component.mjs

@@ -34,6 +34,11 @@ import {componentDetailSource} from './detail/source/source.mjs';
 import {componentDetailShowcase} from './detail/showcase/showcase.mjs';
 import {componentDetailBlocks} from './detail/blocks/blocks.mjs';
 
+/** @type {ReadonlyArray<string>} */
+const DETAIL_LEVELS = ['full', 'compact', 'brief'];
+/** @type {ReadonlyArray<string>} */
+const LANGS = ['en', 'zh', 'dense'];
+
 /**
  * @param {string} [name]
  * @param {object} [options]
@@ -81,6 +86,23 @@ export async function component(name, options = {}) {
   const isListView = list || category != null || !name;
   const detail = detailOption ?? (isListView ? 'brief' : 'full');
 
+  // Same accepted values and codes as the CLI's --detail and --lang, checked
+  // first as the CLI parser does.
+  if (!DETAIL_LEVELS.includes(detail)) {
+    throw new AstryxError(
+      `Invalid detail "${String(detail)}". Valid levels: ${DETAIL_LEVELS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DETAIL,
+    );
+  }
+  if (lang != null && !LANGS.includes(lang)) {
+    throw new AstryxError(
+      `Invalid lang "${String(lang)}". Valid values: ${LANGS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_LANG,
+    );
+  }
+
   const coreDir = requireCoreDir(cwd);
 
   // A public API caller could pass a non-string category; the list leaf does
@@ -143,7 +165,7 @@ export async function component(name, options = {}) {
           : componentDetailShowcase(dirName, {cwd, name, resolve: false});
       }
       if (blocks) {
-        return componentDetailBlocks(dirName);
+        return componentDetailBlocks(dirName, cwd);
       }
       const docs = await loadComponentDoc(owner.docPath, docOpts);
       if (props) return componentDetailProps(docs);
@@ -156,6 +178,13 @@ export async function component(name, options = {}) {
     }
     const extDocPath = resolveLegacyExternalDoc(scoped.ext, dirName);
     if (extDocPath) {
+      // Legacy packages ship docs, never source.
+      if (source) {
+        return componentDetailSource(dirName, null, {name, notFoundInPackage: packageScope});
+      }
+      if (blocks) {
+        return componentDetailBlocks(dirName, cwd);
+      }
       const docs = await loadComponentDoc(extDocPath, docOpts);
       if (props) return componentDetailProps(docs);
       return componentDetail(docs, {package: scoped.ext.name, sourcePath: null}, dirName, coreDir);
@@ -195,7 +224,7 @@ export async function component(name, options = {}) {
 
   // ── Blocks mode ──────────────────────────────────────────────
   if (blocks) {
-    return componentDetailBlocks(dirName);
+    return componentDetailBlocks(dirName, cwd);
   }
 
   // ── Sub-component scoping ────────────────────────────────────

package/api/component/component.test.mjs

@@ -14,6 +14,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {component} from './component.mjs';
 import {AstryxError} from '../error.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
 
 // api/component/ -> up 4 = repo root (has packages/core, which findCoreDir walks to).
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
@@ -161,3 +162,40 @@ describe('component dispatcher — category guard', () => {
     }
   }, SLOW);
 });
+
+describe('component dispatcher — detail and lang guards', () => {
+  // `detail` and `lang` are the same controls as the CLI's --detail and --lang:
+  // same accepted values, same error codes.
+  it('rejects a detail level the CLI rejects, with the same code', async () => {
+    const cliRun = await runCli(['--json', 'component', '--list', '--detail', 'bogus'], cwd);
+    expect(cliRun.code).toBe(1);
+    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_DETAIL');
+
+    const bogus = /** @type {any} */ ('bogus');
+    for (const call of [
+      () => component(undefined, {cwd, list: true, detail: bogus}),
+      () => component('Button', {cwd, detail: bogus}),
+    ]) {
+      const err = await call().catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_INVALID_DETAIL');
+    }
+  }, SLOW);
+
+  it('rejects a lang the CLI rejects, with the same code', async () => {
+    const cliRun = await runCli(['--json', 'component', 'Button', '--lang', 'fr'], cwd);
+    expect(cliRun.code).toBe(1);
+    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_LANG');
+
+    for (const call of [
+      () => component('Button', {cwd, lang: 'fr'}),
+      () => component(undefined, {cwd, list: true, detail: 'compact', lang: 'fr'}),
+    ]) {
+      const err = await call().catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_INVALID_LANG');
+    }
+    const zh = await component('Button', {cwd, lang: 'zh'});
+    expect(zh.type).toBe('component.detail');
+  }, SLOW);
+});

package/api/component/component.type.d.mts

@@ -31,9 +31,10 @@ export type ComponentListData = ({
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  */
 export type ComponentListEntry = {
     name: string;
@@ -42,7 +43,7 @@ export type ComponentListEntry = {
      */
     package: string;
     /**
-     * - Import specifier; present for integration components, absent for core.
+     * - Import specifier; present for integration and legacy package components, absent for core.
      */
     import?: string | undefined;
 };
@@ -59,7 +60,17 @@ export type ComponentBriefEntry = {
  */
 export type ComponentDetailResponse = {
     type: "component.detail";
-    data: import("@astryxdesign/cli/authoring").ComponentDoc & ComponentOwnership;
+    data: import("@astryxdesign/cli/authoring").ComponentDoc & ComponentOwnership & ComponentDetailScope;
+};
+/**
+ * Present only when the requested name is a sub-component documented inside a
+ * parent's doc (e.g. `HStack` in the `Stack` doc); the payload is scoped to it.
+ */
+export type ComponentDetailScope = {
+    /**
+     * - Name of the parent doc the payload was scoped from, e.g. 'Stack'.
+     */
+    parentDoc?: string | undefined;
 };
 /**
  * Ownership metadata attached to every `component.detail` payload. Exposes the

package/api/component/component.type.mjs

@@ -52,13 +52,14 @@
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  * @typedef {object} ComponentListEntry
  * @property {string} name
  * @property {string} package - Owner package, e.g. '@astryxdesign/core' or '@acme/astryx-meta'.
- * @property {string} [import] - Import specifier; present for integration components, absent for core.
+ * @property {string} [import] - Import specifier; present for integration and legacy package components, absent for core.
  */
 
 /**
@@ -73,7 +74,14 @@
  * astryx --json component <name>
  * @typedef {object} ComponentDetailResponse
  * @property {'component.detail'} type
- * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership} data
+ * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership & ComponentDetailScope} data
+ */
+
+/**
+ * Present only when the requested name is a sub-component documented inside a
+ * parent's doc (e.g. `HStack` in the `Stack` doc); the payload is scoped to it.
+ * @typedef {object} ComponentDetailScope
+ * @property {string} [parentDoc] - Name of the parent doc the payload was scoped from, e.g. 'Stack'.
  */
 
 /**

package/api/component/detail/blocks/blocks.d.mts

@@ -6,6 +6,7 @@
  * envelope, splitting them into the hero showcase, component-specific examples,
  * and broader related blocks.
  * @param {string} componentName
+ * @param {string} cwd - project to discover blocks from; never the process cwd
  * @returns {Promise<import('../../component.type.mjs').ComponentDetailBlocksResponse>}
  */
-export function componentDetailBlocks(componentName: string): Promise<import("../../component.type.mjs").ComponentDetailBlocksResponse>;
+export function componentDetailBlocks(componentName: string, cwd: string): Promise<import("../../component.type.mjs").ComponentDetailBlocksResponse>;

package/api/component/detail/blocks/blocks.mjs

@@ -3,7 +3,7 @@
 /**
  * @file `component.detail.blocks` leaf — a component's example/related blocks.
  *
- * @input  a component name
+ * @input  a component name + the project cwd
  * @output the `component.detail.blocks` envelope (showcase, examples, related)
  * @position api/component/detail/blocks (projection leaf; routed by component.mjs)
  */
@@ -16,10 +16,11 @@ import {findRelatedBlocks} from '../../../template/template.mjs';
  * envelope, splitting them into the hero showcase, component-specific examples,
  * and broader related blocks.
  * @param {string} componentName
+ * @param {string} cwd - project to discover blocks from; never the process cwd
  * @returns {Promise<import('../../component.type.mjs').ComponentDetailBlocksResponse>}
  */
-export async function componentDetailBlocks(componentName) {
-  const allBlocks = await findRelatedBlocks(componentName);
+export async function componentDetailBlocks(componentName, cwd) {
+  const allBlocks = await findRelatedBlocks(componentName, cwd);
   const toEntry = (/** @type {any} */ b) => ({
     name: b.dirName,
     displayName: b.name,

package/api/component/list/list.d.mts

@@ -1,11 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
- * @typedef {import('../component.type.mjs').ComponentListEntry} ComponentListEntry
- * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
- */
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in

package/api/component/list/list.mjs

@@ -17,13 +17,14 @@ import {
   discoverExternalComponentsGrouped,
   discoverIntegrationComponents,
   findComponentReadme,
+  findExternalComponentDoc,
   resolveImportPath,
   resolveIntegrationImportPath,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
-import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
+import {loadComponentDoc, loadIntegrationsSafely, withOwnership} from '../_adapter.mjs';
 
 /**
  * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
@@ -31,6 +32,29 @@ import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
  * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
  */
 
+/**
+ * The import a legacy `pkg.astryx.docs` component's detail reports, derived the
+ * same way (`withOwnership`) so list and detail agree.
+ * @param {{name: string, docsDir: string}} ext
+ * @param {string} name
+ * @param {string} coreDir
+ * @param {{zh: boolean, lang: string|null}} docOpts
+ * @returns {Promise<string>}
+ */
+async function legacyImport(ext, name, coreDir, docOpts) {
+  const docPath = findExternalComponentDoc(ext.docsDir, name);
+  /** @type {import('../_adapter.mjs').LoadedComponentDoc} */
+  let docs = {};
+  if (docPath && docPath.endsWith('.doc.mjs')) {
+    try {
+      docs = await loadComponentDoc(docPath, docOpts);
+    } catch {
+      // Keep list resilient; validation owns malformed docs.
+    }
+  }
+  return withOwnership(docs, {package: ext.name, sourcePath: null}, name, coreDir).import;
+}
+
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in
@@ -267,20 +291,24 @@ export async function componentList(
       k => grouped[k].length > 1 || grouped[k][0] !== k,
     );
 
-    if (hasGroups) {
-      for (const [group, members] of Object.entries(grouped)) {
-        listData[`${group} (${ext.name})`] = members.map(n => ({
+    /** @param {string[]} names */
+    const entriesFor = names =>
+      Promise.all(
+        names.map(async n => ({
           name: n,
           package: ext.name,
-        }));
+          import: await legacyImport(ext, n, coreDir, {zh, lang}),
+        })),
+      );
+
+    if (hasGroups) {
+      for (const [group, members] of Object.entries(grouped)) {
+        listData[`${group} (${ext.name})`] = await entriesFor(members);
       }
     } else {
       const allComps = Object.values(grouped).flat().sort();
       if (allComps.length > 0) {
-        listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
-          name: n,
-          package: ext.name,
-        }));
+        listData[`${ext.category} (${ext.name})`] = await entriesFor(allComps);
       }
     }
   }

package/api/discover/discover.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
       name: 'options.components',
       type: 'boolean',
       description:
-        'List components only. A CLI display flag consumed by the renderer; the programmatic response shape is unchanged.',
+        'In the CLI package list, print every component of each package instead of the first 10. A display flag for the CLI renderer; the programmatic response is unchanged.',
     },
     {
       name: 'options.lang',

package/api/gap-report/gap-report.doc.mjs

@@ -32,17 +32,19 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        'Component or general design-system area. Required unless listCategories is true.',
+        'Component or general design-system area, up to 120 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.category',
       type: 'GapReportCategory',
-      description: 'Fixed category from the reported category vocabulary.',
+      description:
+        'Fixed category from the reported category vocabulary. Required unless listCategories is true.',
     },
     {
       name: 'options.reason',
       type: 'string',
-      description: 'What capability was missing or difficult.',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.detail',
@@ -65,7 +67,8 @@ export const doc = {
     {
       name: 'options.listCategories',
       type: 'boolean',
-      description: 'Return categories without resolving a route or writing.',
+      description:
+        'Return categories without resolving a route or writing; the component and every other option are ignored.',
       default: 'false',
     },
     {

package/api/init/init.doc.mjs

@@ -90,6 +90,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();'},

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