@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/search/search.test.mjs

@@ -0,0 +1,512 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the `search` leaf (api/search/search.mjs), run
+ * against the real @astryxdesign/core registry. `search` had no api-level tests;
+ * this locks the envelope, ranking invariants, the `--type`/limit handling, and
+ * the error paths.
+ *
+ * The API validates its own inputs (not just the CLI): a non-positive/non-integer
+ * `limit`, an empty query, and a bad `--type` all throw AstryxError with the
+ * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the
+ * same contract as `astryx search` on the command line.
+ *
+ * The last describe block covers integration-contributed components, using the
+ * same temp-consumer harness as template-integration.test.mjs. Before this,
+ * `search`/`build` only ever scanned @astryxdesign/core — an integration's own
+ * components were invisible to both, even though `component --list` and
+ * `component <Name>` already resolved them. The two discovery paths silently
+ * disagreed.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {
+  search,
+  scoreCandidate,
+  scoreQuery,
+  tokenizeQuery,
+  SEARCH_DOMAINS,
+} from './search.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const cwd = REPO;
+const SLOW = 30_000;
+
+describe('search leaf — envelope + ranking', () => {
+  it('returns a `search` envelope with query + results', async () => {
+    const r = await search('button', {cwd});
+    expect(r.type).toBe('search');
+    expect(r.data.query).toBe('button');
+    expect(Array.isArray(r.data.results)).toBe(true);
+    expect(r.data.results.length).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('keeps tokenizer coverage out of the public result shape', async () => {
+    const r = await search('table of contents', {cwd});
+    expect(r.data.results.length).toBeGreaterThan(0);
+    for (const result of r.data.results) {
+      expect(result).not.toHaveProperty('matchedTerms');
+      expect(result).not.toHaveProperty('queryTerms');
+    }
+  }, SLOW);
+
+  it('returns an empty result set (not an error) for a no-match query', async () => {
+    const r = await search('zzznomatch99', {cwd});
+    expect(r.type).toBe('search');
+    expect(r.data.results).toEqual([]);
+  }, SLOW);
+
+  it('defaults to at most 20 results', async () => {
+    const r = await search('button', {cwd});
+    expect(r.data.results.length).toBeLessThanOrEqual(20);
+  }, SLOW);
+
+  it('caps results to a positive limit', async () => {
+    const r = await search('button', {cwd, limit: 2});
+    expect(r.data.results.length).toBeLessThanOrEqual(2);
+  }, SLOW);
+});
+
+describe('search leaf — per-domain result fields', () => {
+  it('carries import for components and hooks, title for docs, displayName and kind for templates', async () => {
+    const r = await search('theme', {cwd, limit: 60});
+    expect(new Set(r.data.results.map(res => res.domain))).toEqual(
+      new Set(SEARCH_DOMAINS),
+    );
+    for (const res of r.data.results) {
+      expect(typeof res.command).toBe('string');
+      expect(typeof res.description).toBe('string');
+      if (res.domain === 'component' || res.domain === 'hook') {
+        expect(res.import).toMatch(/\S/);
+      } else if (res.domain === 'doc') {
+        expect(res.title).toMatch(/\S/);
+        const read = `astryx docs ${res.name}`;
+        expect([read, `${read} --index`, `${read} ${res.section}`]).toContain(res.command);
+      } else {
+        expect(res.displayName).toMatch(/\S/);
+        expect(['page', 'block']).toContain(res.kind);
+      }
+    }
+  }, SLOW);
+});
+
+describe('search leaf — docs at the grain a reader reads them', () => {
+  it(
+    'finds one section of a guide, and a docs-tree leaf by its own name',
+    async () => {
+      const guide = await search('codemod protected files', {cwd, type: 'doc'});
+      expect(guide.data.results.slice(0, 3)).toContainEqual(
+        expect.objectContaining({
+          domain: 'doc',
+          name: 'cli/integrations',
+          section: 'codemods',
+          title: 'Astryx CLI › CLI Integrations › Codemods',
+          parent: 'astryx docs cli/integrations --index',
+          command: 'astryx docs cli/integrations codemods',
+        }),
+      );
+      const block = await search('token-ref', {cwd});
+      expect(block.data.results[0]).toMatchObject({
+        name: 'authoring',
+        section: 'reference-doc',
+        command: 'astryx docs authoring reference-doc',
+      });
+      const fn = await search('assertResponse', {cwd, type: 'doc'});
+      expect(fn.data.results[0]).toMatchObject({
+        name: 'cli/api/functions/assert-response',
+        title: 'Astryx CLI › API › Functions › assertResponse()',
+        parent: 'astryx docs cli/api/functions',
+        command: 'astryx docs cli/api/functions/assert-response',
+      });
+      expect(fn.data.results[0]).not.toHaveProperty('section');
+    },
+    SLOW,
+  );
+
+  it(
+    'gives a top-level namespace hit the topic list as its parent',
+    async () => {
+      for (const [query, route] of [['unorganized', 'unorganized'], ['Astryx CLI', 'cli']]) {
+        const r = await search(query, {cwd, type: 'doc'});
+        expect(r.data.results).toContainEqual(
+          expect.objectContaining({
+            name: route,
+            command: `astryx docs ${route}`,
+            parent: 'astryx docs',
+          }),
+        );
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'points a topic hit at its index, never a whole-topic read',
+    async () => {
+      const r = await search('cli/integrations', {cwd, type: 'doc'});
+      expect(r.data.results[0]).toMatchObject({
+        name: 'cli/integrations',
+        command: 'astryx docs cli/integrations --index',
+      });
+      expect(r.data.results[0]).not.toHaveProperty('section');
+    },
+    SLOW,
+  );
+
+  it(
+    'searches docs where @astryxdesign/core is not installed',
+    async () => {
+      const bare = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'astryx-search-bare-'),
+      );
+      try {
+        const r = await search('assertResponse', {cwd: bare, type: 'doc'});
+        expect(r.data.results[0].name).toBe(
+          'cli/api/functions/assert-response',
+        );
+      } finally {
+        fs.rmSync(bare, {recursive: true, force: true});
+      }
+    },
+    SLOW,
+  );
+});
+
+describe('search leaf — matchCount is the total, not the cap', () => {
+  it('reports every match while `results` stays bounded by the limit', async () => {
+    // The regression: `matchCount` used to be `results.length`, so a query
+    // matching 57 things reported 20 — the cap read back as the answer. Any
+    // consumer counting matches (the recorded run, a caller paginating) then
+    // could not tell a capped answer from an exactly-cap-sized one.
+    const capped = await search('button', {cwd, limit: 2});
+    expect(capped.data.results.length).toBe(2);
+    expect(capped.data.matchCount).toBeGreaterThan(2);
+
+    // Same query, no meaningful cap: the count is stable across limits, which
+    // is what makes it a count of MATCHES rather than of what was returned.
+    const full = await search('button', {cwd, limit: 500});
+    expect(full.data.matchCount).toBe(capped.data.matchCount);
+    expect(full.data.results.length).toBe(full.data.matchCount);
+  }, SLOW);
+
+  it('reports 0 for a no-match query', async () => {
+    const r = await search('zzznomatch99', {cwd});
+    expect(r.data.matchCount).toBe(0);
+  }, SLOW);
+
+  it('counts only the requested domain under --type', async () => {
+    const all = await search('button', {cwd, limit: 500});
+    const components = await search('button', {
+      cwd,
+      type: 'component',
+      limit: 500,
+    });
+    expect(components.data.matchCount).toBe(components.data.results.length);
+    expect(components.data.matchCount).toBeLessThanOrEqual(all.data.matchCount);
+  }, SLOW);
+});
+
+describe('search leaf — --type filter', () => {
+  it('restricts results to the requested domain', async () => {
+    const r = await search('button', {cwd, type: 'component'});
+    expect(r.data.results.every(x => x.domain === 'component')).toBe(true);
+  }, SLOW);
+
+  it('exposes the valid domain list', () => {
+    expect(SEARCH_DOMAINS).toEqual(expect.arrayContaining(['component', 'hook', 'doc', 'template']));
+  });
+});
+
+describe('search leaf — exact keyword phrase outranks incidental token matches (issue #5239)', () => {
+  it('surfaces Outline for its own declared keyword "table of contents", ranked first', async () => {
+    // Before the fix, "table" and "contents" each separately matched dozens
+    // of unrelated Table-related templates by coincidence, and their
+    // combined token-sum score outranked Outline's single exact match,
+    // pushing it out of the results entirely at the default limit.
+    const r = await search('table of contents', {cwd});
+    expect(r.data.results[0]?.name).toBe('Outline');
+  }, SLOW);
+
+  it('surfaces Outline for its own declared keyword "heading navigation", ranked first', async () => {
+    const r = await search('heading navigation', {cwd});
+    expect(r.data.results[0]?.name).toBe('Outline');
+  }, SLOW);
+
+  it('preserves query coverage metadata on the promoted exact phrase', () => {
+    const query = 'table of contents';
+    const tokens = tokenizeQuery(query);
+    expect(
+      scoreQuery(query, tokens, {
+        name: 'Outline',
+        keywords: [query],
+      }),
+    ).toMatchObject({matched: tokens.length, total: tokens.length});
+  });
+
+  it('still returns no results for a nonsense query (the fix does not loosen matching)', async () => {
+    const r = await search('zzzzqqqx', {cwd});
+    expect(r.data.results).toEqual([]);
+  }, SLOW);
+});
+
+describe('search leaf — error paths (pinned)', () => {
+  it('throws ERR_INVALID_ARGUMENT when the query is empty/whitespace', async () => {
+    await expect(search('   ', {cwd})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringMatching(/query is required/i),
+    });
+  }, SLOW);
+
+  it('throws ERR_INVALID_ARGUMENT for an unknown --type', async () => {
+    await expect(
+      search('button', {cwd, type: /** @type {any} */ ('bogus')}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  }, SLOW);
+
+  it('throws ERR_CORE_NOT_FOUND when @astryxdesign/core cannot be found', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-no-core-'));
+    try {
+      await expect(search('button', {cwd: empty})).rejects.toMatchObject({
+        code: 'ERR_CORE_NOT_FOUND',
+      });
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  }, SLOW);
+});
+
+describe('search leaf — limit validation (API matches the CLI contract)', () => {
+  it('throws ERR_INVALID_ARGUMENT for a limit of 0 (no longer returns everything)', async () => {
+    await expect(search('button', {cwd, limit: 0})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  }, SLOW);
+
+  it('throws ERR_INVALID_ARGUMENT for a negative limit', async () => {
+    await expect(search('button', {cwd, limit: -5})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  }, SLOW);
+
+  it('throws ERR_INVALID_ARGUMENT for a non-integer limit', async () => {
+    await expect(search('button', {cwd, limit: 2.5})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  }, SLOW);
+});
+
+describe('search leaf — integration components', () => {
+  /**
+   * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
+   * resolves without needing the real package) plus an installed
+   * `@acme/widgets` integration that contributes one component.
+   */
+  function makeConsumerWithIntegrationComponent() {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-search-it-'));
+    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`,
+    );
+
+    // Stub core: just needs to exist with an (empty) src/ so discoverComponents
+    // doesn't throw. Its own component list is irrelevant to this test.
+    const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(path.join(coreDir, 'src'), {recursive: true});
+
+    const widgetsDir = path.join(dir, 'node_modules', '@acme', 'widgets');
+    fs.mkdirSync(path.join(widgetsDir, 'components'), {recursive: true});
+    fs.writeFileSync(
+      path.join(widgetsDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'astryx.integration.mjs'),
+      `export default { components: './components' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),
+      `export default {
+        type: 'component',
+        name: 'FancyGizmo',
+        keywords: ['gizmo', 'widget'],
+        usage: {description: 'A fancy gizmo widget.'},
+        props: [],
+      };\n`,
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'components', 'FancyGizmo.tsx'),
+      `export function FancyGizmo() { return null; }\n`,
+    );
+
+    return dir;
+  }
+
+  it('includes a component contributed by a configured integration', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('gizmo', {cwd: dir, type: 'component'});
+      expect(r.data.results.some(x => x.name === 'FancyGizmo')).toBe(true);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('reports the contributing package as the import hint', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('FancyGizmo', {cwd: dir, type: 'component'});
+      const hit = r.data.results.find(x => x.name === 'FancyGizmo');
+      expect(hit?.import).toBe('@acme/widgets');
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+});
+
+describe('search scoring — multi-token aggregation is monotonic', () => {
+  /**
+   * @param {string} q
+   * @param {object} candidate
+   * @returns {number}
+   */
+  const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;
+
+  it('ranks matching both terms above matching only the stronger one', () => {
+    // The shipped regression: scoring averaged over MATCHED tokens, so the
+    // weaker second hit pulled the mean down further than the coverage bonus
+    // pushed it up. `build "file browser"` put two form wizards that matched
+    // only "file" (98) above the actual file browser that matched both (97),
+    // and 98 clears the confident-match gate.
+    const partial = {name: 'form-wizard-vertical', keywords: ['file']};
+    const complete = {
+      name: 'file-explorer',
+      keywords: ['file'],
+      description: 'Column browser for nested folders',
+    };
+    expect(score('file browser', complete)).toBeGreaterThan(score('file browser', partial));
+  });
+
+  it('never scores a superset of matched terms below a subset', () => {
+    const subset = {name: 'zzz-none', keywords: ['alpha']};
+    const supersets = [
+      {name: 'zzz-none', keywords: ['alpha'], description: 'beta things'},
+      {name: 'zzz-none', keywords: ['alpha', 'beta']},
+      {name: 'zzz-none', keywords: ['alpha'], weakKeywords: ['beta']},
+    ];
+    for (const superset of supersets) {
+      expect(score('alpha beta', superset)).toBeGreaterThanOrEqual(score('alpha beta', subset));
+    }
+  });
+
+  it('still scores a verbose prompt on the concepts it did hit', () => {
+    // Guards the reason the mean was used: a long prompt matching one concept
+    // strongly must not be crushed by dividing across every query token.
+    const candidate = {name: 'kanban', keywords: ['kanban']};
+    expect(score('i need a kanban somewhere in this rambling request', candidate))
+      .toBeGreaterThanOrEqual(90);
+  });
+});
+
+describe('search scoring — derived keywords rank below authored ones', () => {
+  it('scores an authored keyword above a derived one', () => {
+    const authored = scoreCandidate('dialog', {name: 'x', keywords: ['Dialog']});
+    const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
+    expect(authored?.score).toBe(90);
+    expect(derived?.score).toBe(60);
+  });
+
+  it('keeps one incidental derived match below the confident-match gate', () => {
+    // PAGE_DIRECT in api/build/kit is 95: at full keyword strength a page that
+    // renders one of everything got a 90-point shot per component and was
+    // returned as a confident match for queries it had nothing to do with.
+    const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
+    expect(derived?.score).toBeLessThan(95);
+  });
+
+  it('still surfaces a derived match above the page floor', () => {
+    // PAGE_FLOOR is 50 — weakening the signal must not make it invisible.
+    const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
+    expect(derived?.score).toBeGreaterThanOrEqual(50);
+  });
+
+  it('explains a derived hit as something the template renders', () => {
+    const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
+    expect(derived?.reason).toMatch(/renders Dialog/);
+  });
+});
+
+describe('search — usage guidance is indexed, a tier below description', () => {
+  // The vocabulary a reader types usually lives in a component's guidance, not
+  // in its one-line description. Banner calls itself "a persistent message";
+  // only its best practices name "caution", "problems", "form errors". Before
+  // this, none of those words found it.
+  const banner = {
+    name: 'Banner',
+    keywords: ['alert', 'notification'],
+    description: 'A persistent message shown above content.',
+    guidance: [
+      'Pick a status that matches the message: info for updates, warning for caution.',
+      'Use error for problems the reader must resolve before continuing.',
+    ],
+  };
+
+  it('finds a term that appears ONLY in guidance', () => {
+    // Red before this change: guidance was never read, so this scored null.
+    const hit = scoreCandidate('caution', banner);
+    expect(hit).not.toBeNull();
+    expect(hit?.reason).toMatch(/guidance mentions "caution"/);
+  });
+
+  it('scores guidance BELOW description, so a component about X outranks one that merely mentions X', () => {
+    const own = scoreCandidate('persistent', banner);
+    const mention = scoreCandidate('caution', banner);
+    expect(own?.score).toBe(50);
+    expect(mention?.score).toBe(45);
+    expect(mention.score).toBeLessThan(own.score);
+  });
+
+  it('never lets guidance outrank a name or keyword hit', () => {
+    expect(scoreCandidate('banner', banner)?.score).toBe(100);
+    expect(scoreCandidate('notification', banner)?.score).toBe(90);
+  });
+
+  it('prefers the stronger signal when a term is in both description and guidance', () => {
+    const both = scoreCandidate('message', banner);
+    expect(both?.score).toBe(50);
+    expect(both?.reason).toMatch(/description mentions/);
+  });
+
+  it('stays below MIN_TOKEN_SCORE, so guidance never counts as a matched CONCEPT', () => {
+    // Measured regression this prevents: counting guidance as a matched term
+    // moved `nested menu` from SideNav to List, and `explain why a field is
+    // required` from Field to TextInput — in both cases a component whose
+    // guidance happens to mention the other word displaced the real answer.
+    // Guidance decides single-word queries; it must not win multi-word ones on
+    // breadth. Same reason weakKeywords are capped.
+    expect(scoreCandidate('caution', banner)?.score).toBeLessThan(50);
+    // Both words are in this candidate's guidance and nowhere else, so if
+    // guidance counted as a concept this would come back as a 2/2 match.
+    const multi = scoreQuery('caution problems', tokenizeQuery('caution problems'), banner);
+    expect(multi).toBeNull();
+  });
+
+  it('lets a real description hit still win the multi-word pass', () => {
+    // The floor must exclude guidance without muting the tiers above it.
+    const hit = scoreQuery('persistent message', tokenizeQuery('persistent message'), banner);
+    expect(hit?.reason).toMatch(/matches 2\/2 terms/);
+  });
+
+  it('tolerates the object-shaped bestPractices entries core actually ships', () => {
+    // Core writes `{guidance: true, description: '...'}`, not plain strings.
+    const hit = scoreCandidate('resolve', {
+      name: 'X',
+      guidance: ['Use error for problems the reader must resolve.'],
+    });
+    expect(hit?.score).toBe(45);
+  });
+});

package/api/swizzle/swizzle.doc.mjs

@@ -29,19 +29,17 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        "Component name to copy (e.g. 'Button'). Omit to list the swizzlable components.",
+        'Bare or XDS-prefixed component name to copy. 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, relative to cwd. An absolute path, or one that resolves outside cwd, throws ERR_PATH_TRAVERSAL.',
+      description: 'Output directory; must resolve inside cwd.',
       default: "'./components/astryx'",
     },
     {
@@ -73,7 +71,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, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
+        '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.',
     },
   ],
   throws: [
@@ -83,7 +81,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      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',
+      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',
@@ -110,7 +108,7 @@ export const doc = {
     {label: 'Eject a component', code: "await swizzle('Button');"},
     {
       label: 'Disambiguate by package',
-      code: "await swizzle('Button', {package: '@astryxdesign/core', overwrite: true});",
+      code: "await swizzle('Button', {package: '@astryxdesign/core'});",
     },
     {
       label: 'Custom output directory',

package/api/template/copy/copy.mjs

@@ -74,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 (or -f) to replace it.`,
+      `Refusing to overwrite existing file ${rel}. Re-run with overwrite to replace it.`,
       undefined,
       ERROR_CODES.ERR_FILE_EXISTS,
     );

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

@@ -35,15 +35,6 @@ 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});

package/api/template/template-integration.test.mjs

@@ -19,6 +19,7 @@ import {
 } from './template.mjs';
 import {search} from '../search/search.mjs';
 import {build} from '../build/build.mjs';
+import {layoutExpand} from '../layout/layout.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
 let tmpDir;
@@ -517,7 +518,53 @@ describe('integration template discovery', () => {
     });
   });
 
-  it('resolves chained block aliases consistently in template', async () => {
+  it('resolves a replacement block through the layout alias', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'acme-card-callout', {
+      kind: 'block',
+      source:
+        'export default function AcmeCardCallout() { return <span>Acme replacement block</span>; }\n',
+    });
+    declareReplaces(pkgDir, {
+      'acme-card-callout': 'CardCallout',
+    });
+
+    const accidental = path.join(tmpDir, 'node_modules', '@acme', 'extra');
+    fs.mkdirSync(path.join(accidental, 'templates'), {recursive: true});
+    fs.writeFileSync(
+      path.join(accidental, 'package.json'),
+      JSON.stringify({name: '@acme/extra', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(accidental, 'astryx.integration.mjs'),
+      `export default {templates: './templates'};\n`,
+    );
+    writeTemplate(accidental, 'CardCallout', {
+      kind: 'block',
+      body: `export default {type: 'block', name: 'ZZZ accidental block', description: 'collision'};\n`,
+      source:
+        'export default function Accidental() { return <span>Accidental block</span>; }\n',
+    });
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default { integrations: ['@acme/widgets', '@acme/extra'] };\n`,
+    );
+
+    const result = await layoutExpand('C{card-callout}', {
+      name: 'ReplacementLayout',
+      cwd: tmpDir,
+    });
+
+    expect(result.data.code).toContain('Acme replacement block');
+    expect(result.data.code).not.toContain('Accidental block');
+    expect(result.data.blocksReferenced).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({name: 'CardCallout', mode: 'splice'}),
+      ]),
+    );
+  }, 30_000);
+
+  it('resolves chained block aliases consistently in template and layout', async () => {
     const [firstTarget, secondTarget] = (await discoverCoreTemplates()).filter(
       candidate => candidate.type === 'block',
     );
@@ -545,12 +592,29 @@ describe('integration template discovery', () => {
       cwd: tmpDir,
     });
     expect(firstTemplate.data.source).toContain('First chain replacement');
+    const layoutId = id =>
+      id.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase();
+    const firstLayout = await layoutExpand(
+      `C{${layoutId(firstTarget.dirName)}}`,
+      {
+        cwd: tmpDir,
+      },
+    );
+    expect(firstLayout.data.code).toContain('First chain replacement');
+    expect(firstLayout.data.code).not.toContain('Final chain replacement');
 
     const secondTemplate = await template(secondTarget.dirName, {
       show: true,
       cwd: tmpDir,
     });
     expect(secondTemplate.data.source).toContain('Final chain replacement');
+    const secondLayout = await layoutExpand(
+      `C{${layoutId(secondTarget.dirName)}}`,
+      {
+        cwd: tmpDir,
+      },
+    );
+    expect(secondLayout.data.code).toContain('Final chain replacement');
   }, 30_000);
 
   it('keeps the old discovery behavior when no replacement is declared', async () => {