@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/search/search.test.mjs

@@ -24,7 +24,10 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {docs} from '../docs/docs.mjs';
 import {
+  headingWithPhrase,
+  titleInQuery,
   search,
   scoreCandidate,
   scoreQuery,
@@ -98,17 +101,18 @@ 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 guide = await search('when a codemod runs', {cwd, type: 'doc'});
+      // Found by the section's own title, wherever the guide sits in the tree.
+      const hit = guide.data.results
+        .slice(0, 3)
+        .find(result => result.section === 'which-codemods-run');
+      expect(hit).toMatchObject({
+        domain: 'doc',
+        name: expect.stringMatching(/^cli\/integrations\/(?:.+\/)?codemods$/),
+        title: expect.stringMatching(/ › Codemods › Choose when a codemod runs$/),
+      });
+      expect(hit.parent).toBe(`astryx docs ${hit.name} --index`);
+      expect(hit.command).toBe(`astryx docs ${hit.name} which-codemods-run`);
       const block = await search('token-ref', {cwd});
       expect(block.data.results[0]).toMatchObject({
         name: 'authoring',
@@ -127,6 +131,30 @@ describe('search leaf — docs at the grain a reader reads them', () => {
     SLOW,
   );
 
+  it(
+    'finds the integration guides for the ways people ask to make one',
+    async () => {
+      // "make", "build", and "an" are stopwords, so each of the first three
+      // tokenizes to `integration` alone; the phrase still matches the
+      // keywords and the title the guides declare. A namespace's own
+      // keywords count, and a plural name is the name.
+      for (const [query, route] of [
+        ['make an integration', /^cli\/integrations$/],
+        ['build an integration', /^cli\/integrations$/],
+        ['create an integration', /^cli\/integrations$/],
+        ['integration', /^cli\/integrations$/],
+        ['publish an integration', /^cli\/integrations$/],
+        // The troubleshooting guide, wherever the tree places it.
+        ['troubleshoot integration', /^cli\/integrations\/(?:.+\/)?troubleshooting$/],
+      ]) {
+        const r = await search(query, {cwd, type: 'doc'});
+        const names = r.data.results.slice(0, 3).map(result => result.name);
+        expect(names.some(name => route.test(name)), `${query}: ${names.join(', ')}`).toBe(true);
+      }
+    },
+    SLOW,
+  );
+
   it(
     'gives a top-level namespace hit the topic list as its parent',
     async () => {
@@ -147,10 +175,15 @@ describe('search leaf — docs at the grain a reader reads them', () => {
   it(
     'points a topic hit at its index, never a whole-topic read',
     async () => {
-      const r = await search('cli/integrations', {cwd, type: 'doc'});
+      // A guide the tree places, read from the tree rather than named.
+      const {data: integrations} = await docs('cli/integrations');
+      const guide = integrations.slots
+        .flatMap(slot => slot.children)
+        .find(child => child.kind === 'generic').route;
+      const r = await search(guide, {cwd, type: 'doc'});
       expect(r.data.results[0]).toMatchObject({
-        name: 'cli/integrations',
-        command: 'astryx docs cli/integrations --index',
+        name: guide,
+        command: `astryx docs ${guide} --index`,
       });
       expect(r.data.results[0]).not.toHaveProperty('section');
     },
@@ -253,6 +286,163 @@ describe('search leaf — exact keyword phrase outranks incidental token matches
   }, SLOW);
 });
 
+describe('search leaf — a whole-query phrase in a title or heading is top tier', () => {
+  /**
+   * @param {string} q
+   * @param {object} candidate
+   * @returns {number}
+   */
+  const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;
+
+  it('finds the whole query, in order, inside a title or heading', () => {
+    expect(headingWithPhrase('dark mode', ['Light/Dark Mode'])).toBe('Light/Dark Mode');
+    expect(headingWithPhrase('nested theme', ['Theme Props', 'Nested themes'])).toBe(
+      'Nested themes',
+    );
+    // A plural on either side is the same word.
+    expect(headingWithPhrase('data attributes selector', ['Data attribute selectors'])).toBe(
+      'Data attribute selectors',
+    );
+    // Out of order, split up, or one word: not a phrase.
+    expect(headingWithPhrase('mode dark', ['Light/Dark Mode'])).toBeNull();
+    expect(headingWithPhrase('dark mode', ['Dark sidebar and mode toggle'])).toBeNull();
+    expect(headingWithPhrase('dark', ['Light/Dark Mode'])).toBeNull();
+    expect(headingWithPhrase('dark mode', undefined)).toBeNull();
+  });
+
+  it('ranks a section titled with the phrase above an exact code-tick match of one word', () => {
+    // The reported miss: `search "dark mode"` put "Light/Dark Mode" at #28,
+    // under API enum docs that name `mode` in code ticks.
+    const section = {name: 'light-dark-mode', titles: ['Light/Dark Mode'], keywords: ['Light/Dark Mode']};
+    const enumDoc = {name: 'response-types', keywords: ['mode', 'dark'], description: 'mode'};
+    expect(score('dark mode', section)).toBe(170);
+    expect(score('dark mode', section)).toBeGreaterThan(score('dark mode', enumDoc));
+  });
+
+  it('ranks a question that names a whole title just below that', () => {
+    expect(titleInQuery('how do i add dark mode', ['Dark mode'])).toBe('Dark mode');
+    expect(titleInQuery('how do nested themes work', ['Nested themes'])).toBe('Nested themes');
+    // One-word titles are too common to count, and order still matters.
+    expect(titleInQuery('how do i theme my app', ['Theme'])).toBeNull();
+    expect(titleInQuery('mode dark please', ['Dark mode'])).toBeNull();
+    const section = {name: 'light-dark-mode', titles: ['Dark mode'], keywords: ['Dark mode']};
+    const named = score('how do i add dark mode', section);
+    expect(named).toBeGreaterThanOrEqual(160);
+    expect(named).toBeLessThan(170);
+    // Sections that share a title are ordered by how much of the rest of the
+    // question they answer.
+    const spacing = {name: 'best-practices', titles: ['Best Practices'], prose: ['Use spacing tokens']};
+    const color = {name: 'best-practices', titles: ['Best Practices'], prose: ['Use color tokens']};
+    expect(score('best practices for spacing', spacing)).toBeGreaterThan(
+      score('best practices for spacing', color),
+    );
+  });
+
+  it('reads a plural of a name as the name, and only a real plural', () => {
+    // One point under the exact spelling, so the doc named `tokens` outranks
+    // the Token component for `tokens`.
+    expect(scoreCandidate('integration', {name: 'integrations'})?.score).toBe(99);
+    expect(scoreCandidate('box', {name: 'boxes'})?.score).toBe(99);
+    expect(scoreCandidate('tabs', {name: 'tab'})?.score).toBe(99);
+    expect(scoreCandidate('tokens', {name: 'tokens'})?.score).toBe(100);
+    // `es` only follows s, x, z, ch, or sh.
+    expect(scoreCandidate('not', {name: 'notes'})?.score ?? 0).toBeLessThan(100);
+    expect(scoreCandidate('mod', {name: 'modes'})?.score ?? 0).toBeLessThan(100);
+  });
+
+  it('keeps an exact name or keyword above a title phrase', () => {
+    const titled = {name: 'x', titles: ['Table of contents for long pages']};
+    const keyword = {name: 'Outline', keywords: ['table of contents']};
+    expect(score('table of contents', keyword)).toBeGreaterThan(score('table of contents', titled));
+  });
+
+  it('puts the dark mode section first for a docs search', async () => {
+    for (const query of ['dark mode', 'how do I add dark mode']) {
+      const r = await search(query, {cwd, type: 'doc'});
+      expect(r.data.results[0]).toMatchObject({name: 'theme', section: 'light-dark-mode'});
+    }
+  }, SLOW);
+});
+
+describe('search leaf — a candidate that matches every word outranks a partial match', () => {
+  /**
+   * @param {string} q
+   * @param {object} candidate
+   * @returns {number}
+   */
+  const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;
+
+  it('ranks a doc with both words above a doc named after one of them', () => {
+    // The reported regression: `search troubleshoot integration` put the
+    // troubleshooting guide 30th, under docs that each match `integration`
+    // alone (by name, 108; in a code tick, 98).
+    const guide = {
+      name: 'troubleshooting',
+      keywords: ['Troubleshooting'],
+      description: 'What to check when an integration does not load.',
+    };
+    const byName = {name: 'integration', keywords: ['integration-add']};
+    const byCodeTick = {name: 'integration-add', keywords: ['integration']};
+    const q = 'troubleshoot integration';
+    expect(score(q, guide)).toBeGreaterThan(score(q, byName));
+    expect(score(q, guide)).toBeGreaterThan(score(q, byCodeTick));
+    expect(scoreQuery(q, tokenizeQuery(q), guide)).toMatchObject({matched: 2, total: 2});
+  });
+
+  it('holds for longer queries too, and stays below the title tiers', () => {
+    const all = {name: 'x', keywords: ['alphas'], description: 'alpha beta gamma delta'};
+    const threeOfFour = {name: 'alpha', keywords: ['beta', 'gamma']};
+    const q = 'alpha beta gamma delta';
+    expect(score(q, all)).toBeGreaterThan(score(q, threeOfFour));
+    expect(score(q, all)).toBeLessThan(160);
+  });
+
+  // Among candidates that match every word, the stronger match should come
+  // first. Today every all-word match with a keyword hit gets the same score,
+  // so this records the order without enforcing it: it fails, as expected,
+  // until the scoring tells the two apart.
+  it.fails('ranks the stronger of two all-word matches first', () => {
+    const all = {name: 'x', keywords: ['alphas'], description: 'alpha beta gamma delta'};
+    const q = 'alpha beta gamma delta';
+    expect(score(q, {name: 'y', keywords: ['alpha'], description: 'beta gamma delta'})).toBeGreaterThan(
+      score(q, all),
+    );
+  });
+
+  it('keeps passing mentions of every word below an exact hit on one word', () => {
+    // Mentions in prose, or the components a page happens to render, are
+    // breadth: a page that says "empty state" is not the EmptyState answer.
+    const mentions = {name: 'ai-chat-landing', description: 'A landing page with an empty state.'};
+    const keyword = {name: 'x', keywords: ['empty']};
+    expect(score('empty state', mentions)).toBeLessThan(score('empty state', keyword));
+  });
+
+  it('finds a component by its name typed as words, and a guide by its route', async () => {
+    for (const [query, name] of [
+      ['command palette', 'CommandPalette'],
+      ['empty state', 'EmptyState'],
+    ]) {
+      const r = await search(query, {cwd});
+      expect(r.data.results[0], query).toMatchObject({domain: 'component', name});
+    }
+    const tokens = await search('tokens', {cwd});
+    expect(tokens.data.results[0]).toMatchObject({domain: 'doc', name: 'tokens'});
+    for (const [query, route] of [
+      ['codemods', /^cli\/integrations\/(?:.+\/)?codemods$/],
+      ['quick start', /^cli\/integrations\/(?:.+\/)?quick-start$/],
+      ['test in an app', /^cli\/integrations\/(?:.+\/)?test-in-an-app$/],
+    ]) {
+      const r = await search(query, {cwd, type: 'doc'});
+      // The guide is among the hits that share the top score: two guides
+      // that both declare the phrase tie, and the tie's order is not pinned.
+      const top = r.data.results
+        .filter(result => result.score === r.data.results[0].score)
+        .map(result => result.name);
+      expect(top.some(name => route.test(name)), `${query}: ${top.join(', ')}`).toBe(true);
+    }
+  }, 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({
@@ -267,12 +457,20 @@ describe('search leaf — error paths (pinned)', () => {
     ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
   }, SLOW);
 
-  it('throws ERR_CORE_NOT_FOUND when @astryxdesign/core cannot be found', async () => {
+  it('searches the docs without @astryxdesign/core, and throws for a domain that needs it', 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',
-      });
+      // An open search outside an app covers the docs, as `astryx docs` does.
+      const open = await search('make an integration', {cwd: empty});
+      expect(open.data.results.length).toBeGreaterThan(0);
+      expect(new Set(open.data.results.map(r => r.domain))).toEqual(
+        new Set(['doc']),
+      );
+      for (const type of ['component', 'hook', 'template']) {
+        await expect(
+          search('button', {cwd: empty, type: /** @type {any} */ (type)}),
+        ).rejects.toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
+      }
     } finally {
       fs.rmSync(empty, {recursive: true, force: true});
     }

package/api/swizzle/copy/copy.mjs

@@ -25,7 +25,7 @@ import {
   findIntegrationComponentSource,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {AstryxError} from '../../error.mjs';
+import {AstryxError, writeFailed} from '../../error.mjs';
 
 /** Default issue tracker for maintainer feedback after swizzling. */
 const DEFAULT_ISSUES_URL = 'https://github.com/facebook/astryx/issues/new';
@@ -290,11 +290,21 @@ export async function swizzleCopy(component, options = {}) {
     );
   }
 
-  fs.mkdirSync(outputDir, {recursive: true});
+  const outputDirExisted = fs.existsSync(outputDir);
+  try {
+    fs.mkdirSync(outputDir, {recursive: true});
+  } catch (err) {
+    throw writeFailed(outputDir, cwd, err);
+  }
 
   const files = fs.readdirSync(componentDir);
   let copied = 0;
   let usesStyleX = false;
+  // A copy that fails part-way undoes what it already wrote, so the report is
+  // true and a retry does not trip over half a component. Each entry keeps
+  // the bytes the file had before this run (null when the copy created it).
+  /** @type {Array<{dest: string, original: Buffer|null}>} */
+  const written = [];
   for (const file of files) {
     if (isExcludedFromCopy(file)) continue;
     const srcPath = path.join(componentDir, file);
@@ -309,7 +319,25 @@ export async function swizzleCopy(component, options = {}) {
     ) {
       usesStyleX = true;
     }
-    fs.writeFileSync(path.join(outputDir, file), content);
+    const dest = path.join(outputDir, file);
+    try {
+      // The snapshot read is guarded too: a destination that cannot be read
+      // back (no permission, or a directory with this name) must still undo
+      // the earlier writes and report ERR_WRITE_FAILED.
+      const original = fs.existsSync(dest) ? fs.readFileSync(dest) : null;
+      written.push({dest, original});
+      fs.writeFileSync(dest, content);
+    } catch (err) {
+      const unrestored = undoCopy(written);
+      if (!outputDirExisted) {
+        try {
+          fs.rmdirSync(outputDir);
+        } catch {
+          // Not empty (something could not be undone), or already gone.
+        }
+      }
+      throw writeFailed(dest, cwd, err, unrestored);
+    }
     copied++;
   }
 
@@ -333,3 +361,38 @@ export async function swizzleCopy(component, options = {}) {
   if (feedback) data.feedback = feedback;
   return {type: 'swizzle.copy', data};
 }
+
+/**
+ * Undo the writes of a copy that failed part-way, newest first: delete the
+ * files the copy created and put back the bytes of the files it replaced. A
+ * file whose bytes are already the original ones is left alone, so a write
+ * that failed before changing anything is not reported as unrestored.
+ *
+ * @param {Array<{dest: string, original: Buffer|null}>} written
+ * @returns {string[]} the files it could not restore
+ */
+function undoCopy(written) {
+  /** @type {string[]} */
+  const unrestored = [];
+  for (const {dest, original} of [...written].reverse()) {
+    try {
+      if (original == null) {
+        fs.rmSync(dest, {force: true});
+        continue;
+      }
+      /** @type {Buffer|null} */
+      let current = null;
+      try {
+        current = fs.readFileSync(dest);
+      } catch {
+        current = null;
+      }
+      if (current == null || !current.equals(original)) {
+        fs.writeFileSync(dest, original);
+      }
+    } catch {
+      unrestored.push(dest);
+    }
+  }
+  return unrestored;
+}

package/api/swizzle/swizzle.doc.mjs

@@ -29,17 +29,19 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        'Bare or XDS-prefixed component name to copy. Omit to list the swizzlable components.',
+        "Component name to copy (e.g. 'Button'). 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; must resolve inside cwd.',
+      description:
+        'Output directory, relative to cwd. An absolute path, or one that resolves outside cwd, throws ERR_PATH_TRAVERSAL.',
       default: "'./components/astryx'",
     },
     {
@@ -71,7 +73,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 an optional maintainer-feedback note.',
+        '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.',
     },
   ],
   throws: [
@@ -81,7 +83,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      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',
+      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',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
@@ -99,6 +101,10 @@ export const doc = {
       code: 'ERR_FILE_EXISTS',
       when: 'copying would overwrite existing files and overwrite is not set',
     },
+    {
+      code: 'ERR_WRITE_FAILED',
+      when: 'the output directory or a copied file could not be written (no permission, read-only mount, full disk)',
+    },
   ],
   examples: [
     {
@@ -108,7 +114,7 @@ export const doc = {
     {label: 'Eject a component', code: "await swizzle('Button');"},
     {
       label: 'Disambiguate by package',
-      code: "await swizzle('Button', {package: '@astryxdesign/core'});",
+      code: "await swizzle('Button', {package: '@astryxdesign/core', overwrite: true});",
     },
     {
       label: 'Custom output directory',

package/api/template/copy/copy.mjs

@@ -16,9 +16,9 @@ import {
   isFilePathArg,
   PathSafetyError,
 } from '../../../foundation/fs/path-safety.mjs';
-import {AstryxError} from '../../error.mjs';
+import {AstryxError, writeFailed} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {stripTemplateAssetRefs} from '../../../foundation/discovery/template-adapter.mjs';
+import {replaceDemoMedia} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Scaffold an already-resolved template to `targetPath` (relative to `cwd`) and
@@ -74,19 +74,24 @@ 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 to replace it.`,
+      `Refusing to overwrite existing file ${rel}. Re-run with --overwrite (or -f) to replace it.`,
       undefined,
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
 
-  fs.mkdirSync(outputDir, {recursive: true});
-
   // Strip demo image references so the scaffolded file renders without a
-  // Meta-only network dependency.
-  const source = fs.readFileSync(match.filePath, 'utf-8');
-  const outputSource = stripTemplateAssetRefs(source);
-  fs.writeFileSync(outputFilePath, outputSource);
+  // Meta-only network dependency. Read before any write, so a failure below
+  // leaves nothing behind.
+  const {source: outputSource, demoMediaReplaced} = replaceDemoMedia(
+    fs.readFileSync(match.filePath, 'utf-8'),
+  );
+  try {
+    fs.mkdirSync(outputDir, {recursive: true});
+    fs.writeFileSync(outputFilePath, outputSource);
+  } catch (err) {
+    throw writeFailed(outputFilePath, cwd, err);
+  }
 
   const relOutput = path.relative(cwd, outputDir) || '.';
   return {
@@ -96,6 +101,7 @@ export function templateCopy(match, {targetPath, cwd, overwrite = false}) {
       outputDir: relOutput,
       fileName: outputFileName,
       filesCopied: 1,
+      demoMediaReplaced,
     },
   };
 }

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

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The template.copy receipt discloses replaced demo media. Templates are
+ * picked by what their source contains, not by slug, so catalog renames do not
+ * break the suite.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {template, discoverTemplates} from '../template.mjs';
+
+const SLOW = 60_000;
+const FIXTURE_REF = /\/template-assets\/[\w.-]+\.(\w+)/g;
+const VIDEO = new Set(['mp4', 'webm', 'mov', 'ogv', 'm4v']);
+
+/** @param {string} filePath */
+const fixtureRefs = filePath =>
+  [...fs.readFileSync(filePath, 'utf-8').matchAll(FIXTURE_REF)].map(m =>
+    m[1].toLowerCase(),
+  );
+
+/**
+ * @param {(refs: string[]) => boolean} predicate
+ * @param {'page' | 'block'} type
+ */
+async function findTemplate(type, predicate) {
+  const all = /** @type {Array<{dirName: string, type: string, filePath: string}>} */ (
+    await discoverTemplates()
+  );
+  const ids = new Map();
+  for (const t of all) ids.set(t.dirName, (ids.get(t.dirName) ?? 0) + 1);
+  const found = all.find(
+    t =>
+      t.type === type &&
+      ids.get(t.dirName) === 1 &&
+      fs.existsSync(t.filePath) &&
+      predicate(fixtureRefs(t.filePath)),
+  );
+  if (!found) throw new Error(`no ${type} template matches`);
+  return {id: found.dirName, refs: fixtureRefs(found.filePath)};
+}
+
+describe('template.copy receipt — replaced demo media', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmpl-receipt-'));
+  });
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  it('counts every demo image a page template carried, and leaves none behind', async () => {
+    const {id, refs} = await findTemplate(
+      'page',
+      r => r.length > 0 && r.every(ext => !VIDEO.has(ext)),
+    );
+    const res = await template(id, {targetPath: './dest', cwd: dir});
+    expect(res.type).toBe('template.copy');
+    expect(res.data.demoMediaReplaced).toBe(refs.length);
+    expect(
+      fs.readFileSync(path.join(dir, 'dest', 'page.tsx'), 'utf-8'),
+    ).not.toContain('/template-assets/');
+  }, SLOW);
+
+  it('counts a demo video in a block template', async () => {
+    const {id, refs} = await findTemplate('block', r => r.some(ext => VIDEO.has(ext)));
+    const res = await template(id, {targetPath: './dest', cwd: dir});
+    expect(res.data.demoMediaReplaced).toBe(refs.length);
+  }, SLOW);
+
+  it('reports 0 when the template carries no demo media', async () => {
+    const {id} = await findTemplate('page', r => r.length === 0);
+    const res = await template(id, {targetPath: './dest', cwd: dir});
+    expect(res.data.demoMediaReplaced).toBe(0);
+  }, SLOW);
+});

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

@@ -35,6 +35,15 @@ 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/show/show.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `template.show` leaf — return a resolved template's raw source plus the
- * components it composes.
+ * @file `template.show` leaf — return a resolved template's source, exactly as
+ * `template.copy` writes it, plus the components it composes.
  *
  * @position api/template/show — reads the resolved match's source file; the
  *   template dispatcher routes `show` (and the no-target-path default) here.
@@ -11,7 +11,10 @@
 import * as fs from 'node:fs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {extractComponents} from '../../../foundation/discovery/template-adapter.mjs';
+import {
+  extractComponents,
+  replaceDemoMedia,
+} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Build the `template.show` envelope for an already-resolved template.
@@ -27,6 +30,13 @@ export function templateShow(match) {
     );
   }
 
+  // The source template.copy writes (spec:AST-028 FR7): a template printed and
+  // pasted must not keep a media path only Astryx's previews serve, and the
+  // caller is told how many it replaced, the way the copy receipt tells it.
+  const {source, demoMediaReplaced} = replaceDemoMedia(
+    fs.readFileSync(match.filePath, 'utf-8'),
+  );
+
   return {
     type: 'template.show',
     data: {
@@ -34,7 +44,8 @@ export function templateShow(match) {
       description: match.description,
       type: match.type,
       components: extractComponents(match.filePath),
-      source: fs.readFileSync(match.filePath, 'utf-8'),
+      source,
+      demoMediaReplaced,
     },
   };
 }