@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/clients/cli/commands/integration.mjs

@@ -12,6 +12,7 @@ import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as integrationGroup} from './integration.doc.mjs';
 import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
 import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
 import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
 import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
@@ -24,8 +25,16 @@ import {doc as integrationPackCheckFn} from '../../../api/integration/integratio
  */
 function showGroupOrUnknown(command, label, options, invoked) {
   const extras = invoked?.args ?? [];
-  if (extras.length > 0) {
-    return cliError(`unknown subcommand '${label} ${String(extras[0])}'`, {
+  // allowUnknownOption keeps an unknown flag among the args: a word there is
+  // an unknown subcommand, and a flag alone is an unknown option.
+  const word = extras.find(arg => !String(arg).startsWith('-'));
+  if (word == null && extras.length > 0) {
+    return cliError(`unknown option '${String(extras[0])}'`, {
+      code: ERROR_CODES.ERR_INVALID_OPTION,
+    });
+  }
+  if (word != null) {
+    return cliError(`unknown subcommand '${label} ${String(word)}'`, {
       suggestions: (command.commands ?? []).map(child => ({
         name: child.name(),
         reason: 'available subcommand',
@@ -37,6 +46,48 @@ function showGroupOrUnknown(command, label, options, invoked) {
   return NO_RESULT_SET;
 }
 
+/**
+ * Run `integration verify` and print its result, as text or JSON.
+ * @param {import('commander').Command} program
+ */
+async function verifyPackage(program) {
+  const result = await integrationPackCheck({cwd: process.cwd()});
+  if (program.opts().json) {
+    jsonOut(result);
+  } else {
+    const {name, version, packable, tarball, inventory, issues} = result.data;
+    const identity = [name, version].filter(Boolean).join('@');
+    const blocks = [
+      section(
+        packable
+          ? 'Integration package ready'
+          : 'Integration package check failed',
+      ),
+      text(`${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`),
+    ];
+    if (tarball != null) {
+      blocks.push(
+        text(
+          `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
+        ),
+      );
+    }
+    if (issues.length > 0) {
+      blocks.push(
+        list(
+          issues.map(
+            issue =>
+              `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
+          ),
+        ),
+      );
+    }
+    emit(...blocks);
+  }
+  if (!result.data.packable) process.exitCode = 1;
+  return NO_RESULT_SET;
+}
+
 /** @param {import('commander').Command} program */
 export function registerIntegration(program) {
   /** @type {import('commander').Command} */
@@ -45,6 +96,10 @@ export function registerIntegration(program) {
     action: (options, command) =>
       showGroupOrUnknown(integration, 'integration', options, command),
   });
+  // An unknown subcommand given with a flag reports the unknown subcommand
+  // and lists the ones the group has, not the unknown option. Each subcommand
+  // still parses its own options.
+  integration.allowUnknownOption(true);
 
   defineCommand(integration, integrationAddCommand, {
     fn: integrationAddFn,
@@ -60,6 +115,7 @@ export function registerIntegration(program) {
           extends: options.extends,
           parent: options.parent,
           to: options.to,
+          from: options.from,
         });
       } catch (error) {
         const err =
@@ -102,53 +158,30 @@ export function registerIntegration(program) {
     },
   });
 
+  defineCommand(integration, integrationVerifyCommand, {
+    fn: integrationPackCheckFn,
+    action: async () => verifyPackage(program),
+  });
+  // The name this check had before `integration verify`. It stays as a
+  // deprecated alias, listed as one in help, so scripts that call it keep
+  // working; it runs the same check with the same output and exit codes.
   defineCommand(integration, integrationPackCommand, {
     fn: integrationPackCheckFn,
     action: async options => {
       if (!options.check) {
-        return cliError('Pass --check to verify the integration tarball.', {
-          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
-        });
+        // One way forward: the new name. `npm pack` is what builds a tarball.
+        return cliError(
+          '`integration pack` is now `integration verify`: run `astryx integration verify` to check the package the way npm will publish it. To build the tarball, run `npm pack`.',
+          {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
+        );
       }
-
-      const result = await integrationPackCheck({cwd: process.cwd()});
-      if (program.opts().json) {
-        jsonOut(result);
-      } else {
-        const {name, version, packable, tarball, inventory, issues} =
-          result.data;
-        const identity = [name, version].filter(Boolean).join('@');
-        const blocks = [
-          section(
-            packable
-              ? 'Integration package ready'
-              : 'Integration package check failed',
-          ),
-          text(
-            `${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`,
-          ),
-        ];
-        if (tarball != null) {
-          blocks.push(
-            text(
-              `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
-            ),
-          );
-        }
-        if (issues.length > 0) {
-          blocks.push(
-            list(
-              issues.map(
-                issue =>
-                  `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
-              ),
-            ),
-          );
-        }
-        emit(...blocks);
+      // stderr, and only in text: JSON callers get the same envelope as verify.
+      if (!program.opts().json) {
+        console.error(
+          'Note: `integration pack --check` is deprecated. Run `astryx integration verify`: it runs the same check.',
+        );
       }
-      if (!result.data.packable) process.exitCode = 1;
-      return NO_RESULT_SET;
+      return verifyPackage(program);
     },
   });
 }

package/clients/cli/commands/layout-expand.doc.mjs

@@ -18,7 +18,9 @@ export const doc = {
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
     'ready-to-use XDS TSX, routing children into slots, scaffolding typed useState for ' +
-    'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
+    'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code. ' +
+    'Astryx demo media in a spliced block becomes a placeholder, and the output says how many ' +
+    'references were replaced (as a closing line comment when it prints the code).',
   fn: 'layoutExpand',
   args: [
     {

package/clients/cli/commands/layout.expand-receipt.test.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout expand` tells the caller, in JSON and in text, when demo
+ * media in a spliced template block was replaced with placeholders. Printed
+ * code stays verbatim and valid TSX: the disclosure follows it as a comment.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import ts from 'typescript';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {discoverTemplates} from '../../../api/template/template.mjs';
+
+const SLOW = 60_000;
+const DISCLOSURE = /demo media/i;
+
+/** @param {string} name */
+const hintKey = name => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** @param {string} source */
+const tsxErrors = source =>
+  /** @type {any} */ (
+    ts.createSourceFile('out.tsx', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  ).parseDiagnostics.map((/** @type {ts.Diagnostic} */ d) =>
+    ts.flattenDiagnosticMessageText(d.messageText, ' '),
+  );
+
+/** A `{hint}` for a template block whose source carries demo media. */
+async function mediaBlockHint() {
+  const blocks = /** @type {Array<{dirName: string, type: string, filePath: string}>} */ (
+    await discoverTemplates()
+  ).filter(t => t.type === 'block' && t.filePath && fs.existsSync(t.filePath));
+  const seen = new Map();
+  for (const t of blocks) seen.set(hintKey(t.dirName), (seen.get(hintKey(t.dirName)) ?? 0) + 1);
+  const found = blocks.find(
+    t =>
+      seen.get(hintKey(t.dirName)) === 1 &&
+      /\/template-assets\/[\w.-]+\.\w+/.test(fs.readFileSync(t.filePath, 'utf-8')),
+  );
+  if (!found) throw new Error('no template block carries demo media');
+  return hintKey(found.dirName);
+}
+
+describe('layout expand discloses replaced demo media', () => {
+  let cwd;
+  beforeEach(() => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-media-receipt-'));
+  });
+  afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
+
+  it('--json carries demoMediaReplaced; the text receipt states it for the written file', async () => {
+    const expr = `V > {${await mediaBlockHint()}}`;
+    const json = await runCli(['layout', 'expand', expr, './a', '--json'], cwd);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.demoMediaReplaced).toBeGreaterThan(0);
+
+    const human = await runCli(['layout', 'expand', expr, './b'], cwd);
+    expect(human.status).toBe(0);
+    expect(human.stdout).toContain(
+      `Replaced ${data.demoMediaReplaced} Astryx demo media reference`,
+    );
+    expect(human.stdout).toContain(path.join('b', 'GeneratedLayout.tsx'));
+  }, SLOW);
+
+  it('prints the code verbatim, then states the count in a comment that keeps it valid TSX', async () => {
+    const expr = `V > {${await mediaBlockHint()}}`;
+    const {data} = JSON.parse((await runCli(['layout', 'expand', expr, '--json'], cwd)).stdout);
+
+    const human = await runCli(['layout', 'expand', expr], cwd);
+    expect(human.status).toBe(0);
+    expect(human.stdout.startsWith(data.code)).toBe(true);
+    expect(human.stdout.slice(data.code.length).trim()).toMatch(
+      new RegExp(`^// Replaced ${data.demoMediaReplaced} Astryx demo media references? in the code above: [^\\n]+$`),
+    );
+    expect(tsxErrors(human.stdout)).toEqual([]);
+  }, SLOW);
+
+  it('says nothing about demo media when none was replaced', async () => {
+    const json = await runCli(['layout', 'expand', 'V > B"Save"', '--json'], cwd);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.demoMediaReplaced).toBe(0);
+
+    const written = await runCli(['layout', 'expand', 'V > B"Save"', './a'], cwd);
+    expect(written.status).toBe(0);
+    expect(written.stdout).not.toMatch(DISCLOSURE);
+    const printed = await runCli(['layout', 'expand', 'V > B"Save"'], cwd);
+    expect(printed.status).toBe(0);
+    expect(printed.stdout).toBe(`${data.code}\n`);
+  }, SLOW);
+});

package/clients/cli/commands/layout.mjs

@@ -120,6 +120,20 @@ async function readExpression(expr, options = {}) {
   return expr ?? '';
 }
 
+/**
+ * The disclosure for demo media replaced in spliced template blocks, or '' when
+ * none was. After printed code it is a line comment, so piped output stays TSX.
+ * @param {LayoutExpandResponse['data']} data
+ * @returns {string}
+ */
+function demoMediaNotice({demoMediaReplaced, written}) {
+  if (demoMediaReplaced === 0) return '';
+  const notice =
+    `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'} in ${written ?? 'the code above'}: ` +
+    'images now show a neutral placeholder and videos have an empty source. Supply your own media there.';
+  return written ? notice : `// ${notice}`;
+}
+
 /**
  * @param {import('commander').Command} program
  */
@@ -181,6 +195,8 @@ export function registerLayout(program) {
         // Raw expanded TSX (no target path) — preformatted, emitted verbatim.
         out.push(code(result.data.code));
       }
+      const mediaNotice = demoMediaNotice(result.data);
+      if (mediaNotice) out.push(text(mediaNotice));
       emit(...out);
       return NO_RESULT_SET;
     },

package/clients/cli/commands/manifest.doc.mjs

@@ -20,7 +20,7 @@ export const doc = {
     'tooling to introspect. Intended to be run with --json.',
   examples: [
     {label: 'Full manifest', cli: 'astryx manifest --json'},
-    {label: 'Shorthand', cli: 'astryx --json'},
+    {label: 'The same manifest, under data.manifest (type "help")', cli: 'astryx --json'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

package/clients/cli/commands/search.doc.mjs

@@ -16,9 +16,12 @@ export const doc = {
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
     'Terminal front-end to search(): prints one ranked, greppable list across ' +
-    'every content domain, each row carrying a follow-up command to act on it.',
+    'every content domain, each row carrying a follow-up command to act on it. ' +
+    'Outside an app, where @astryxdesign/core is not installed, it searches the docs.',
   fn: 'search',
-  args: [{name: 'query', param: 'query', required: true}],
+  // Every word after `search` is the query: `astryx search dark mode` searches
+  // for "dark mode", with no quotes needed.
+  args: [{name: 'query', param: 'query', required: true, variadic: true}],
   options: [
     {
       flag: '--type <domain>',
@@ -38,6 +41,10 @@ export const doc = {
   ],
   examples: [
     {label: 'Ranked results', cli: 'astryx search button'},
+    {
+      label: 'Several words, no quotes',
+      cli: 'astryx search dark mode --type doc',
+    },
     {
       label: 'Filter + JSON',
       cli: 'astryx search "data table" --type template --json',
@@ -47,7 +54,7 @@ export const doc = {
     {code: 0, when: 'success (including zero matches)'},
     {
       code: 1,
-      when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
+      when: 'invalid --type, a --limit that is not a positive integer, or --type component, hook, or template where @astryxdesign/core cannot be found',
     },
   ],
   related: ['component', 'hook', 'docs', 'template', 'build'],

package/clients/cli/commands/search.mjs

@@ -14,6 +14,7 @@
  *
  * Usage:
  *   astryx search button                 Ranked results across all domains
+ *   astryx search dark mode              Every word is part of the query
  *   astryx search modal --type component Filter to a single domain
  *   astryx search forms --limit 5        Cap the result count
  *   astryx search button --verbose       Also print score / reason
@@ -31,6 +32,7 @@ import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {search as searchApi} from '../../../api/search/search.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
 import {doc as searchCommand} from './search.doc.mjs';
 import {doc as searchFn} from '../../../api/search/search.doc.mjs';
@@ -42,10 +44,13 @@ export function registerSearch(program) {
   defineCommand(program, searchCommand, {
     fn: searchFn,
     action: async (
-      /** @type {string} */ query,
+      /** @type {string[] | string} */ words,
       /** @type {{type?: import('../../../api/search/search.type.mjs').SearchDomain, limit?: string, verbose?: boolean}} */ options,
     ) => {
       const json = program.opts().json || false;
+      // The query is variadic: `astryx search dark mode` is one query, "dark
+      // mode". Taking only the first word dropped the rest without a word.
+      const query = Array.isArray(words) ? words.join(' ') : words;
 
       try {
         const project = await Project.load(process.cwd());
@@ -99,12 +104,25 @@ export function registerSearch(program) {
       // ── Text output ──────────────────────────────────────────────
       const run = getCliInvocation();
       const {query: q, matchCount, results} = result.data;
+      // Outside an app an open search covers the docs alone. Say so, so a
+      // docs-only list does not read as "Astryx has no such component".
+      const note =
+        !options.type && !findCoreDir(process.cwd())
+          ? [
+              text(
+                '@astryxdesign/core is not installed here, so only the docs were searched.',
+              ),
+            ]
+          : [];
 
       // No matches is a valid, successful outcome — clean message, exit 0.
       if (results.length === 0) {
         emit(
           text(`No results for "${q}".`),
-          text(`Try a broader term, or browse: ${run} component --list`),
+          ...note,
+          text(
+            `Try a broader term, or browse: ${run} ${note.length > 0 ? 'docs' : 'component --list'}`,
+          ),
         );
         return answered;
       }
@@ -155,6 +173,7 @@ export function registerSearch(program) {
           fields,
           format: {command: formatCliCommand, parent: formatCliCommand},
         }),
+        ...note,
       );
       return answered;
     },

package/clients/cli/commands/search.test.mjs

@@ -191,6 +191,18 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('No results');
   });
 
+  it('takes every word after `search` as one query', async () => {
+    // Commander took only the first word, so `search dark mode` searched for
+    // "dark" and dropped "mode" without a word.
+    const json = await runCli(['--json', 'search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.query).toBe('dark mode');
+    expect(env.data.results[0]).toMatchObject({name: 'theme', section: 'light-dark-mode'});
+    const text = await runCli(['search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
+    expect(text.stdout).toContain('Results for "dark mode"');
+  }, SCAN_TIMEOUT);
+
   it('exits 1 for an invalid --type', async () => {
     const r = await runCli(['search', 'x', '--type', 'bogus'], REPO_ROOT);
     expect(r.status).toBe(1);
@@ -299,14 +311,19 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('reason:');
   });
 
-  it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
+  it('searches the docs when no @astryxdesign/core is reachable, and exits 1 for --type component', async () => {
     const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
     try {
-      const json = await runCli(['--json', 'search', 'button'], empty);
+      const open = await runCli(['--json', 'search', 'make', 'an', 'integration'], empty);
+      expect(open.status).toBe(0);
+      expect(JSON.parse(open.stdout).data.results[0]).toMatchObject({domain: 'doc'});
+      // The text says the search covered the docs alone.
+      const text = await runCli(['search', 'button'], empty);
+      expect(text.status).toBe(0);
+      expect(text.stdout).toContain('only the docs were searched');
+      const json = await runCli(['--json', 'search', 'button', '--type', 'component'], empty);
       expect(json.status).toBe(1);
       expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
-      const text = await runCli(['search', 'button'], empty);
-      expect(text.status).toBe(1);
     } finally {
       fs.rmSync(empty, {recursive: true, force: true});
     }

package/clients/cli/commands/swizzle.doc.mjs

@@ -46,7 +46,7 @@ export const doc = {
   ],
   examples: [
     {label: 'List swizzlable components', cli: 'astryx swizzle --list'},
-    {label: 'Eject a component', cli: 'astryx swizzle XDSButton'},
+    {label: 'Eject a component', cli: 'astryx swizzle Button'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

package/clients/cli/commands/template.copy-receipt.test.mjs

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx template <name> <path>` tells the caller, in JSON and in text,
+ * when demo media in the copied file was replaced with placeholders.
+ */
+
+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 {runCli} from '../../../test-utils/run-cli.mjs';
+import {discoverTemplates} from '../../../api/template/template.mjs';
+
+const SLOW = 60_000;
+
+/** A page template whose source carries demo media, and one that carries none. */
+async function pickPages() {
+  const pages = /** @type {Array<{dirName: string, type: string, filePath: string}>} */ (
+    await discoverTemplates()
+  ).filter(t => t.type === 'page' && fs.existsSync(t.filePath));
+  const hasMedia = (/** @type {{filePath: string}} */ t) =>
+    /\/template-assets\/[\w.-]+\.\w+/.test(fs.readFileSync(t.filePath, 'utf-8'));
+  const withMedia = pages.find(hasMedia);
+  const without = pages.find(t => !hasMedia(t));
+  if (!withMedia || !without) throw new Error('catalog lacks a page with and without demo media');
+  return {withMedia: withMedia.dirName, without: without.dirName};
+}
+
+describe('template copy receipt discloses replaced demo media', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmpl-receipt-cli-'));
+  });
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  it('--json carries demoMediaReplaced and the text states the same count', async () => {
+    const {withMedia} = await pickPages();
+    const json = await runCli(['template', withMedia, './a', '--json'], dir);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.demoMediaReplaced).toBeGreaterThan(0);
+
+    const human = await runCli(['template', withMedia, './b'], dir);
+    expect(human.status).toBe(0);
+    expect(human.stdout).toContain(
+      `Replaced ${data.demoMediaReplaced} Astryx demo media reference`,
+    );
+    expect(human.stdout).toContain('b/page.tsx');
+  }, SLOW);
+
+  it('says nothing about media when none was replaced', async () => {
+    const {without} = await pickPages();
+    const json = await runCli(['template', without, './a', '--json'], dir);
+    expect(JSON.parse(json.stdout).data.demoMediaReplaced).toBe(0);
+    const human = await runCli(['template', without, './b'], dir);
+    expect(human.status).toBe(0);
+    expect(human.stdout).not.toMatch(/demo media/i);
+  }, SLOW);
+});

package/clients/cli/commands/template.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   name: 'template',
   displayName: 'astryx template',
   namespace: 'cli/commands',
-  summary: 'Inject a page or block template',
+  summary: 'List, show, or scaffold page and block templates',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +

package/clients/cli/commands/template.mjs

@@ -156,16 +156,30 @@ export function registerTemplate(program) {
         }
 
         case 'template.show': {
-          // Source must survive piping byte-for-byte.
-          emit(code(result.data.source));
+          // Source must survive piping byte-for-byte, so the note about
+          // replaced demo media goes to stderr, in the copy receipt's words.
+          // (Text mode only: --json returned above with the count in data.)
+          const {source, demoMediaReplaced} = result.data;
+          emit(code(source));
+          if (demoMediaReplaced > 0) {
+            console.error(
+              `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'}: ` +
+                'images now show a neutral placeholder and videos have an empty source. Supply your own media there.',
+            );
+          }
           break;
         }
 
         case 'template.copy': {
+          const {outputDir, fileName, demoMediaReplaced} = result.data;
+          const file = `${outputDir}/${fileName}`;
           emit(
-            text(
-              `Copied template to ${result.data.outputDir}/${result.data.fileName}`,
-            ),
+            text(`Copied template to ${file}`),
+            demoMediaReplaced > 0 &&
+              text(
+                `Replaced ${demoMediaReplaced} Astryx demo media reference${demoMediaReplaced === 1 ? '' : 's'} in ${file}: ` +
+                  'images now show a neutral placeholder and videos have an empty source. Supply your own media there.',
+              ),
           );
           break;
         }

package/clients/cli/commands/template.show-media.test.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx template <name>` says how many demo media references it
+ * replaced: in `--json` as `demoMediaReplaced`, and in text on stderr, so that
+ * stdout stays exactly the source a copy writes and can be piped into a file.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {discoverTemplates} from '../../../api/template/template.mjs';
+
+const SLOW = 60_000;
+
+/** A page template whose source carries demo media, and one that carries none. */
+async function pickPages() {
+  const pages = /** @type {Array<{dirName: string, type: string, filePath: string}>} */ (
+    await discoverTemplates()
+  ).filter(t => t.type === 'page' && fs.existsSync(t.filePath));
+  const hasMedia = (/** @type {{filePath: string}} */ t) =>
+    /\/template-assets\/[\w.-]+\.\w+/.test(fs.readFileSync(t.filePath, 'utf-8'));
+  const withMedia = pages.find(hasMedia);
+  const without = pages.find(t => !hasMedia(t));
+  if (!withMedia || !without) throw new Error('catalog lacks a page with and without demo media');
+  return {withMedia: withMedia.dirName, without: without.dirName};
+}
+
+describe('template show discloses replaced demo media', () => {
+  /** @type {string} */
+  let dir;
+  beforeAll(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmpl-show-cli-'));
+  });
+  afterAll(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  it('--json carries demoMediaReplaced, and text states it on stderr with stdout left as the source', async () => {
+    const {withMedia} = await pickPages();
+    const json = await runCli(['template', withMedia, '--type', 'page', '--json'], dir);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.demoMediaReplaced).toBeGreaterThan(0);
+
+    const human = await runCli(['template', withMedia, '--type', 'page'], dir);
+    expect(human.status).toBe(0);
+    expect(human.stdout.trimEnd()).toBe(data.source.trimEnd());
+    expect(human.stderr).toContain(
+      `Replaced ${data.demoMediaReplaced} Astryx demo media reference`,
+    );
+  }, SLOW);
+
+  it('says nothing about media when none was replaced', async () => {
+    const {without} = await pickPages();
+    const json = await runCli(['template', without, '--type', 'page', '--json'], dir);
+    expect(JSON.parse(json.stdout).data.demoMediaReplaced).toBe(0);
+    const human = await runCli(['template', without, '--type', 'page'], dir);
+    expect(human.status).toBe(0);
+    expect(human.stderr).not.toMatch(/demo media/i);
+  }, SLOW);
+});

package/clients/cli/commands/text-json-parity.test.mjs

@@ -372,9 +372,15 @@ const CASES = [
     skipFieldChecks: true,
   },
   {
+    name: 'integration verify',
+    args: ['integration', 'verify'],
+    // Needs a packable project; pack itself may exit differently.
+    skipFieldChecks: true,
+  },
+  {
+    // The deprecated alias of `integration verify`.
     name: 'integration pack',
     args: ['integration', 'pack', '--check'],
-    // Needs a packable project; pack itself may exit differently.
     skipFieldChecks: true,
   },
   // ── Layout command: remove these cases when the layout command is deleted ──