@astryxdesign/cli 0.1.6 → 0.1.7-canary.04cd8f7

package/src/api/docOverlays.test.mjs

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the --dense / --zh reference-doc overlays against drift (#2182).
+ * @input packages/cli/docs/{topic}.doc.mjs and its .doc.dense.mjs / .doc.zh.mjs overlays.
+ * @output Vitest failures naming any overlay section that does not anchor to a
+ *   real base section, or whose content overrides land on the wrong block type.
+ * @position Regression gate for the docs API. Sits with the loader it guards.
+ *
+ * The overlays used to be applied BY ARRAY POSITION, so an overlay whose
+ * sections were ordered differently from the base grafted every title onto the
+ * wrong body. `docs tokens --dense` printed the entire colour table under a
+ * heading that said "## Spacing", above prose reading "gap props use
+ * space0-space12" — teaching any agent that spacing tokens are named
+ * `--color-*`. CLAUDE.md tells every agent to run that exact command at
+ * bootstrap, which is what made a doc bug into a codegen bug.
+ *
+ * Overlays now anchor to a base section by title, so a reordered or
+ * partial overlay is correct by construction. These tests keep it that way.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {docs} from './docs.mjs';
+
+const DOCS_DIR = path.join(import.meta.dirname, '..', '..', 'docs');
+
+/** Every base reference doc that has at least one overlay. */
+function overlayPairs() {
+  const pairs = [];
+  for (const file of fs.readdirSync(DOCS_DIR)) {
+    const m = file.match(/^(.+)\.doc\.(dense|zh)\.mjs$/);
+    if (!m) continue;
+    const [, topic, variant] = m;
+    pairs.push({
+      topic,
+      variant,
+      basePath: path.join(DOCS_DIR, `${topic}.doc.mjs`),
+      overlayPath: path.join(DOCS_DIR, file),
+    });
+  }
+  return pairs;
+}
+
+async function load(p) {
+  return await import(pathToFileURL(p).href);
+}
+
+describe('reference doc overlays (#2182)', () => {
+  const pairs = overlayPairs();
+
+  it('finds overlays to check', () => {
+    // A rename that stops overlays being discovered must not silently pass.
+    expect(pairs.length).toBeGreaterThan(0);
+  });
+
+  for (const {topic, variant, basePath, overlayPath} of pairs) {
+    it(`${topic} --${variant}: every overlay section anchors to a real base section`, async () => {
+      const base = await load(basePath);
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+
+      const baseTitles = base.docs.sections.map(s => s.title);
+      const unanchored = (overlay.sections || [])
+        .filter(s => s.section == null || !baseTitles.includes(s.section))
+        .map(s => s.section ?? `(no anchor) "${s.title}"`);
+
+      expect(
+        unanchored,
+        `${topic}.doc.${variant}.mjs has section entries that do not name a ` +
+          `base section via \`section:\`. Without an anchor the overlay is ` +
+          `applied by array position, which silently grafts each title onto ` +
+          `the wrong body. Base sections are: ${baseTitles.join(', ')}.`,
+      ).toEqual([]);
+    });
+
+    it(`${topic} --${variant}: no base section is overridden twice`, async () => {
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+      const anchors = (overlay.sections || []).map(s => s.section);
+      const dupes = anchors.filter((a, i) => anchors.indexOf(a) !== i);
+      expect(dupes, `${topic}.doc.${variant}.mjs overrides the same base section twice`).toEqual([]);
+    });
+  }
+});
+
+describe('the reported defect: docs tokens --dense (#2182)', () => {
+  it('does not print the colour table under the Spacing heading', async () => {
+    const result = await docs('tokens', null, {dense: true});
+    const spacing = result.data.sections.find(s => /spacing/i.test(s.title));
+    expect(spacing, 'tokens docs should have a spacing section').toBeTruthy();
+
+    const text = JSON.stringify(spacing);
+    expect(
+      text.includes('--color-'),
+      `The "${spacing.title}" section of \`docs tokens --dense\` contains ` +
+        `colour tokens. An agent reading this learns that spacing tokens are ` +
+        `named --color-*.`,
+    ).toBe(false);
+    expect(text).toContain('--spacing-');
+  });
+
+  it('keeps every base section reachable, even without an overlay entry', async () => {
+    // The tokens overlay compresses only 6 of 13 sections. The other 7 must
+    // still render (in English), not vanish or absorb a neighbour's title.
+    const full = await docs('tokens', null, {});
+    const dense = await docs('tokens', null, {dense: true});
+    expect(dense.data.sections.length).toBe(full.data.sections.length);
+  });
+
+  it('does not lose the Extending a Theme section from docs theme --dense', async () => {
+    const dense = await docs('theme', null, {dense: true});
+    const titles = dense.data.sections.map(s => s.title);
+    expect(titles).toContain('Extending a Theme');
+  });
+
+  it('does not emit a duplicate useTheme heading in docs theme --dense', async () => {
+    const dense = await docs('theme', null, {dense: true});
+    const titles = dense.data.sections.map(s => s.title.toLowerCase());
+    const useTheme = titles.filter(t => t.includes('usetheme'));
+    expect(useTheme.length).toBe(1);
+  });
+
+  it('does not leak English headings into docs theme --zh', async () => {
+    const zh = await docs('theme', null, {zh: true});
+    const titles = zh.data.sections.map(s => s.title);
+    // Every section the overlay translates must appear once, in Chinese only.
+    expect(titles).not.toContain('Light/Dark Mode');
+    expect(titles).toContain('亮/暗模式');
+  });
+});

package/src/api/docs.mjs

@@ -38,11 +38,23 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   const translation = translationMod.docsZh || translationMod.docsDense;
   if (!translation) return docs;
 
+  // Overlays are keyed to a base section by title (`section`), not by array
+  // position. Position-keying silently grafted each overlay title onto whatever
+  // base section happened to share its index, so an overlay that omitted or
+  // reordered a section corrupted every section after it — `docs tokens --dense`
+  // printed the colour table under a "Spacing" heading (#2182). An overlay may
+  // now cover any subset of sections, in any order; sections it does not name
+  // keep their base content.
+  const bySection = new Map();
+  for (const ts of translation.sections ?? []) {
+    if (ts?.section != null) bySection.set(ts.section, ts);
+  }
+
   return {
     ...docs,
     description: translation.description || docs.description,
-    sections: docs.sections.map((section, si) => {
-      const ts = translation.sections?.[si];
+    sections: docs.sections.map(section => {
+      const ts = bySection.get(section.title);
       if (!ts) return section;
       return {
         ...section,

package/src/api/doctor.mjs

@@ -26,7 +26,7 @@ import {createRequire} from 'node:module';
 
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
 import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
-import {detectPackageManager} from '../utils/package-manager.mjs';
+import {detectPackageManager, getCliInvocation} from '../utils/package-manager.mjs';
 import {findConfigPath, Project} from '../lib/project.mjs';
 import {semverCompare} from '../utils/semver.mjs';
 
@@ -343,7 +343,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'info',
       message: 'No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.',
-      fix: 'Generate agent docs with `astryx init --features agents`.',
+      fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
     };
   }
 
@@ -365,7 +365,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
+      fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
     };
   }
 

package/src/api/integration-block-exports.test.mjs

@@ -0,0 +1,240 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Proves the minimal `exports` recipe an integration package needs so a
+ * bundler-resolution consumer can `import()` its block templates AND type-check
+ * them under `moduleResolution: bundler`.
+ *
+ * Integration packages in this ecosystem ship TypeScript SOURCE — their block
+ * templates are `.tsx` files with no compiled `.d.ts`. A later feature renders
+ * showcase previews by a REAL dynamic `import()` of a block's `.tsx` source
+ * (e.g. `import('@acme/widgets/templates/Gauge/GaugeShowcase.tsx')`) instead of
+ * eval'ing source text. For that import to resolve, the integration's
+ * `package.json#exports` map must GATE the deep path.
+ *
+ * These tests stand up a throwaway `@acme/widgets` fixture and drive the two
+ * gates that matter with the repo's own toolchain:
+ *   1. `tsc --noEmit` under `moduleResolution: bundler` (the consumer profile
+ *      used by the Next.js example apps — NO `allowImportingTsExtensions`).
+ *   2. `esbuild --bundle` (a real bundler resolving + loading the deep import).
+ *
+ * CANONICAL RECIPE (see integration-authoring.md):
+ *   exports: { "./templates/*.tsx": "./templates/*.tsx" }
+ *   import:  import('@acme/widgets/templates/<Name>/<Name>Showcase.tsx')   // WITH .tsx
+ *
+ * The negative controls lock in WHY the extension is required: a bare
+ * `./templates/*` export with an extensionless import fails to type-check under
+ * bundler resolution (TS cannot infer the `.tsx` extension for a deep
+ * specifier), and an extensionless import fails to bundle.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {execFileSync} from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+
+/** Resolve the workspace tsc/esbuild binaries; null if unavailable. */
+function resolveBin(spec) {
+  try {
+    return require.resolve(spec);
+  } catch {
+    return null;
+  }
+}
+const TSC_BIN = resolveBin('typescript/bin/tsc');
+const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
+
+let tmpDir;
+
+/**
+ * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
+ * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
+ * manifest, plus a caller-supplied `exports` map.
+ * @param {Record<string, string> | undefined} exportsMap
+ */
+function makeWidgets(exportsMap) {
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  const blockDir = path.join(pkgDir, 'templates', 'Gauge');
+  fs.mkdirSync(blockDir, {recursive: true});
+
+  const pkg = {name: '@acme/widgets', version: '2.0.0', type: 'module'};
+  if (exportsMap) pkg.exports = exportsMap;
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify(pkg, null, 2),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  // The template-spec doc (canonical `.template.*` family).
+  fs.writeFileSync(
+    path.join(blockDir, 'GaugeShowcase.template.ts'),
+    `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
+  );
+  // The same-stem `.tsx` SOURCE that a preview will dynamically import().
+  // Returns a plain value so the fixture type-checks without React types.
+  fs.writeFileSync(
+    path.join(blockDir, 'GaugeShowcase.tsx'),
+    `const GaugeShowcase = (): string => 'gauge-showcase';\n` +
+      `export default GaugeShowcase;\n`,
+  );
+  return pkgDir;
+}
+
+/** Write a consumer that dynamically imports the given specifier. */
+function writeConsumer(specifier) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'consumer.ts'),
+    `const load = () => import('${specifier}');\nexport default load;\n`,
+  );
+}
+
+/**
+ * The realistic consumer tsconfig: matches the repo's Next.js example apps
+ * (`moduleResolution: bundler`, `noEmit`, and deliberately NO
+ * `allowImportingTsExtensions`).
+ */
+function writeTsconfig() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'tsconfig.json'),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ES2022',
+          lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          jsx: 'react-jsx',
+          strict: true,
+          skipLibCheck: true,
+          esModuleInterop: true,
+          noEmit: true,
+          isolatedModules: true,
+        },
+        include: ['consumer.ts'],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+/** @returns {{ok: boolean, out: string}} */
+function runTsc() {
+  try {
+    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
+      cwd: tmpDir,
+      stdio: 'pipe',
+    });
+    return {ok: true, out: ''};
+  } catch (e) {
+    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
+  }
+}
+
+/** @returns {{ok: boolean, out: string}} */
+function runEsbuild() {
+  try {
+    // esbuild's bin is a native executable (not a node script), so invoke it
+    // directly rather than through process.execPath.
+    execFileSync(
+      ESBUILD_BIN,
+      [
+        'consumer.ts',
+        '--bundle',
+        '--format=esm',
+        '--loader:.tsx=tsx',
+        '--outfile=/dev/null',
+        '--log-level=error',
+      ],
+      {cwd: tmpDir, stdio: 'pipe'},
+    );
+    return {ok: true, out: ''};
+  } catch (e) {
+    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-block-exports-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', private: true, type: 'module'}),
+  );
+  writeTsconfig();
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+const CANONICAL = 'import(@acme/widgets/templates/Gauge/GaugeShowcase.tsx)';
+const SPEC = '@acme/widgets/templates/Gauge/GaugeShowcase.tsx';
+
+describe('integration block-template exports recipe', () => {
+  it.runIf(TSC_BIN != null)(
+    `CANONICAL: exports {"./templates/*.tsx"} + ${CANONICAL} type-checks under bundler resolution`,
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer(SPEC);
+      const {ok, out} = runTsc();
+      expect(out).toBe('');
+      expect(ok).toBe(true);
+    },
+    30_000,
+  );
+
+  it.runIf(ESBUILD_BIN != null)(
+    `CANONICAL: the same import resolves + bundles with a real bundler`,
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer(SPEC);
+      const {ok, out} = runEsbuild();
+      expect(out).toBe('');
+      expect(ok).toBe(true);
+    },
+    30_000,
+  );
+
+  it.runIf(TSC_BIN != null)(
+    'NEGATIVE: an extensionless import does NOT type-check (TS cannot infer .tsx)',
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
+      const {ok, out} = runTsc();
+      expect(ok).toBe(false);
+      expect(out).toContain('TS2307');
+    },
+    30_000,
+  );
+
+  it.runIf(TSC_BIN != null)(
+    'NEGATIVE: a bare "./templates/*" export (no .tsx entry) does NOT type-check the .tsx import',
+    () => {
+      // Only a bare mapping — the extensionful subpath is not exported.
+      makeWidgets({'./templates/*': './templates/*'});
+      writeConsumer(SPEC);
+      const {ok, out} = runTsc();
+      expect(ok).toBe(false);
+      // Bare export forces the TS5097 opt-in requirement (allowImportingTsExtensions).
+      expect(out).toContain('TS5097');
+    },
+    30_000,
+  );
+
+  it.runIf(ESBUILD_BIN != null)(
+    'NEGATIVE: an extensionless import does NOT bundle against the .tsx-only export',
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
+      const {ok} = runEsbuild();
+      expect(ok).toBe(false);
+    },
+    30_000,
+  );
+});

package/src/api/template-suffix.test.mjs

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
+ * to the legacy `.doc.{ts,mjs,js}` suffix.
+ *
+ * Template-spec files are named for what they are: a scaffoldable TEMPLATE that
+ * exports `createBlockTemplate`/`createPageTemplate`. The `.doc.*` suffix was
+ * inherited from the component-doc convention and is still accepted during the
+ * transition. These tests stand up integration templates and external blocks in
+ * both families and assert byte-for-byte-equivalent discovery + scaffolding.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  template,
+  findShowcase,
+  findRelatedBlocks,
+} from './template.mjs';
+
+/** Absolute path to the CLI package so fixtures can import /src/template.mjs. */
+const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
+
+let tmpDir;
+let originalCwd;
+
+function makeConsumer() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-suffix-'));
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
+  );
+  return dir;
+}
+
+function installWidgets(consumerDir) {
+  const pkgDir = path.join(consumerDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(path.join(pkgDir, 'templates'), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '2.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  return pkgDir;
+}
+
+/**
+ * Write a template-spec file (default-export createPageTemplate/BlockTemplate)
+ * plus its same-stem `.tsx` source under the templates root.
+ * @param {string} pkgDir
+ * @param {string} id
+ * @param {{kind: 'page'|'block', suffix: string}} opts
+ */
+function writeTemplate(pkgDir, id, {kind, suffix}) {
+  const docPath = path.join(pkgDir, 'templates', `${id}${suffix}`);
+  fs.mkdirSync(path.dirname(docPath), {recursive: true});
+  const create =
+    kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
+  fs.writeFileSync(
+    docPath,
+    `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+      `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'templates', `${id}.tsx`),
+    `export default function ${id.replace(/[^a-zA-Z0-9]/g, '')}() { return null; }\n`,
+  );
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = makeConsumer();
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration templates: .template.* discovered like legacy .doc.*', () => {
+  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
+    it(`discovers + lists a page template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
+
+      const result = await template(undefined, {list: true, cwd: tmpDir});
+      const entry = result.data.find(t => t.id === 'pricing');
+      expect(entry).toBeTruthy();
+      expect(entry.type).toBe('page');
+      expect(entry.package).toBe('@acme/widgets');
+      expect(entry.name).toBe('pricing name');
+      expect(entry.description).toBe('pricing desc');
+    });
+
+    it(`scaffolds a page template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
+
+      const result = await template('pricing', {
+        targetPath: './dest',
+        cwd: tmpDir,
+      });
+      expect(result.type).toBe('template.copy');
+      expect(result.data.fileName).toBe('page.tsx');
+      expect(fs.existsSync(path.join(tmpDir, 'dest', 'page.tsx'))).toBe(true);
+    });
+
+    it(`scaffolds a nested block template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'marketing/hero', {kind: 'block', suffix});
+
+      const result = await template('marketing/hero', {
+        targetPath: './dest',
+        cwd: tmpDir,
+      });
+      expect(result.type).toBe('template.copy');
+      expect(result.data.fileName).toBe('hero.tsx');
+      expect(fs.existsSync(path.join(tmpDir, 'dest', 'hero.tsx'))).toBe(true);
+    });
+  }
+
+  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
+    writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    const gauge = result.data.find(t => t.id === 'gauge');
+    const chip = result.data.find(t => t.id === 'chip');
+
+    // Both discovered, both blocks, both from the same package, both ready.
+    for (const entry of [gauge, chip]) {
+      expect(entry).toBeTruthy();
+      expect(entry.type).toBe('block');
+      expect(entry.package).toBe('@acme/widgets');
+    }
+    // Field-by-field parity apart from the (intentionally different) id/name.
+    expect(gauge.type).toBe(chip.type);
+    expect(gauge.package).toBe(chip.package);
+  });
+});
+
+describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
+  /**
+   * Create a consumer whose @test/ext package contributes two showcase blocks,
+   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
+   */
+  function makeShowcaseFixture() {
+    // Symlink the real core package (needed by findCoreDir during discovery).
+    const realCoreDir = path.resolve(
+      import.meta.dirname,
+      '..',
+      '..',
+      '..',
+      'core',
+    );
+    const coreDir = path.join(tmpDir, 'packages', 'core');
+    fs.mkdirSync(path.dirname(coreDir), {recursive: true});
+    fs.symlinkSync(realCoreDir, coreDir);
+
+    const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
+    const blocksDir = path.join(extDir, 'blocks', 'components');
+
+    // Foo showcase — canonical .template.ts (default-export createBlockTemplate).
+    const fooDir = path.join(blocksDir, 'Foo');
+    fs.mkdirSync(fooDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(fooDir, 'FooShowcase.template.ts'),
+      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+        `export default createBlockTemplate({\n` +
+        `  name: 'Foo — Showcase',\n` +
+        `  description: 'Foo showcase.',\n` +
+        `  isShowcase: true,\n` +
+        `  aspectRatio: 16 / 9,\n` +
+        `  componentsUsed: ['Foo'],\n` +
+        `});\n`,
+    );
+    fs.writeFileSync(
+      path.join(fooDir, 'FooShowcase.tsx'),
+      "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
+    );
+
+    // Bar showcase — legacy .doc.mjs (export const doc).
+    const barDir = path.join(blocksDir, 'Bar');
+    fs.mkdirSync(barDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(barDir, 'BarShowcase.doc.mjs'),
+      `export const doc = {\n` +
+        `  type: 'block',\n` +
+        `  name: 'Bar — Showcase',\n` +
+        `  description: 'Bar showcase.',\n` +
+        `  isReady: true,\n` +
+        `  isShowcase: true,\n` +
+        `  aspectRatio: 4 / 3,\n` +
+        `  componentsUsed: ['Bar', 'Chip'],\n` +
+        `};\n`,
+    );
+    fs.writeFileSync(
+      path.join(barDir, 'BarShowcase.tsx'),
+      "'use client';\nexport default function BarShowcase() { return <div>Bar</div>; }",
+    );
+
+    fs.writeFileSync(
+      path.join(extDir, 'package.json'),
+      JSON.stringify({
+        name: '@test/ext',
+        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+      }),
+    );
+    fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
+  }
+
+  it('findShowcase resolves a .template.ts external block by directory name', async () => {
+    makeShowcaseFixture();
+    const result = await findShowcase('Foo', tmpDir);
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('Foo — Showcase');
+    expect(result.filePath).toContain('FooShowcase.tsx');
+  });
+
+  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
+    makeShowcaseFixture();
+    const result = await findShowcase('Bar', tmpDir);
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('Bar — Showcase');
+  });
+
+  it('findRelatedBlocks finds both suffix families', async () => {
+    makeShowcaseFixture();
+    const foo = await findRelatedBlocks('Foo', tmpDir);
+    expect(foo.map(b => b.dirName)).toContain('FooShowcase');
+    const chip = await findRelatedBlocks('Chip', tmpDir);
+    expect(chip.map(b => b.dirName)).toContain('BarShowcase');
+  });
+});