@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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

@@ -11,6 +11,8 @@
  */
 
 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, SEARCH_DOMAINS} from '../../../api/search/search.mjs';
@@ -28,6 +30,33 @@ const OPTS = {cwd: REPO_ROOT};
 // the vitest per-test timeout. Give both the same generous scan budget.
 const SCAN_TIMEOUT = 30_000;
 
+/**
+ * A JSON value as the formatters print it (they normalize typography to ASCII).
+ * @param {unknown} value
+ */
+function asText(value) {
+  return (Array.isArray(value) ? value.join(', ') : String(value))
+    .replace(/[\u2014\u2013]/g, '-')
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/[\u201C\u201D]/g, '"')
+    .replace(/\u2026/g, '...')
+    .replace(/\u00a0/g, ' ')
+    .trimEnd();
+}
+
+/**
+ * Whether some text line prints `key:` with this value. The command field gains
+ * the caller's invocation prefix, so the value is matched as the line's end; a
+ * multi-line value is matched by its first line.
+ * @param {string[]} lines
+ * @param {string} key
+ * @param {unknown} value
+ */
+function printsField(lines, key, value) {
+  const shown = asText(value).split('\n')[0].trimEnd();
+  return lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown));
+}
+
 describe('search() API — ranking', () => {
   it('ranks an exact component name match first', async () => {
     const {data} = await search('button', OPTS);
@@ -162,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);
@@ -172,6 +213,20 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.status).toBe(1);
   });
 
+  it.each(['1.5', '5abc'])(
+    'refuses --limit %s like search({limit}) does, in both modes',
+    async value => {
+      await expect(
+        search('x', {...OPTS, limit: Number(value)}),
+      ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+      const json = await runCli(['--json', 'search', 'x', '--limit', value], REPO_ROOT);
+      expect(json.status).toBe(1);
+      expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+      const text = await runCli(['search', 'x', '--limit', value], REPO_ROOT);
+      expect(text.status).toBe(1);
+    },
+  );
+
   it('emits a valid --json envelope', async () => {
     const r = await runCli(['--json', 'search', 'button'], REPO_ROOT);
     expect(r.status).toBe(0);
@@ -223,6 +278,25 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('description:');
   });
 
+  it('prints every result field under its JSON key (score and reason with --verbose)', async () => {
+    // One query that reaches all four domains, so every per-domain field shows.
+    const args = ['search', 'theme', '--limit', '60'];
+    const env = JSON.parse((await runCli(['--json', ...args], REPO_ROOT)).stdout);
+    expect(new Set(env.data.results.map(r => r.domain))).toEqual(new Set(SEARCH_DOMAINS));
+    const plain = (await runCli(args, REPO_ROOT)).stdout.split('\n');
+    const verbose = (await runCli([...args, '--verbose'], REPO_ROOT)).stdout.split('\n');
+    for (const result of env.data.results) {
+      for (const [key, value] of Object.entries(result)) {
+        if (value == null || value === '') continue;
+        const label = `${result.domain} ${result.name}: ${key}`;
+        expect(printsField(verbose, key, value), label).toBe(true);
+        if (key !== 'score' && key !== 'reason') {
+          expect(printsField(plain, key, value), label).toBe(true);
+        }
+      }
+    }
+  }, 90_000);
+
   it('--verbose exits 0 and prints import/match detail', async () => {
     // Regression: the boolean verbose flag was named --detail, which collided
     // with the value-taking global `--detail <level>` — a bare `search
@@ -236,4 +310,22 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('score:');
     expect(r.stdout).toContain('reason:');
   });
+
+  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 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'});
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
 }, SCAN_TIMEOUT);

package/clients/cli/commands/setup-nudge.test.mjs

@@ -89,6 +89,12 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in an integration package, which is not an app', async () => {
+    asProject();
+    write('astryx.integration.mjs', 'export default {};\n');
+    expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
+  });
+
   it('does not nudge for the installer command itself', async () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'swizzle',
   displayName: 'astryx swizzle',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Copy component source for customization',
   description:
     "Ejects a component's source from the resolved @astryxdesign/core (or its owning " +
@@ -40,12 +40,13 @@ export const doc = {
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Overwrite existing files without prompting',
+      description:
+        'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
     },
   ],
   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/swizzle.path-safety.test.mjs

@@ -74,6 +74,37 @@ describe('swizzle path safety', () => {
     expect(fs.existsSync(absTarget)).toBe(false);
   });
 
+  it('rejects a component directory that is a symlink out of the project', async () => {
+    const {project, outside} = buildFakeRepo(tmpDir);
+    const base = path.join(project, 'components', 'astryx');
+    fs.mkdirSync(base, {recursive: true});
+    fs.symlinkSync(outside, path.join(base, 'Button'));
+
+    const result = await runCli(['--json', 'swizzle', 'Button'], project);
+
+    expect(result.code).not.toBe(0);
+    expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('rejects an existing file that is a symlink out of the project, even with --overwrite', async () => {
+    const {project, outside} = buildFakeRepo(tmpDir);
+    const outDir = path.join(project, 'components', 'astryx', 'Button');
+    fs.mkdirSync(outDir, {recursive: true});
+    const target = path.join(outside, 'kept.txt');
+    fs.writeFileSync(target, 'kept\n');
+    fs.symlinkSync(target, path.join(outDir, 'Button.tsx'));
+
+    const result = await runCli(
+      ['--json', 'swizzle', 'Button', '--overwrite'],
+      project,
+    );
+
+    expect(result.code).not.toBe(0);
+    expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
+    expect(fs.readFileSync(target, 'utf-8')).toBe('kept\n');
+  });
+
   it('requires --overwrite in non-interactive mode when files already exist', async () => {
     const {project} = buildFakeRepo(tmpDir);
     const outDir = path.join(project, 'components', 'astryx', 'Button');
@@ -92,4 +123,15 @@ describe('swizzle path safety', () => {
     // Existing file unchanged
     expect(fs.readFileSync(existingPath, 'utf-8')).toBe('// my customizations\n');
   });
+
+  // The CLI never prompts: without --overwrite it refuses with a code, and the
+  // manifest agents read must say so.
+  it('describes --overwrite by its refusal, not a prompt', async () => {
+    const {project} = buildFakeRepo(tmpDir);
+    const result = await runCli(['--json', 'manifest'], project);
+    const swizzle = JSON.parse(result.stdout).data.commands.find(c => c.name === 'swizzle');
+    const overwrite = swizzle.options.find(o => o.flag.includes('--overwrite'));
+    expect(overwrite.description).not.toMatch(/prompt/i);
+    expect(overwrite.description).toContain('ERR_FILE_EXISTS');
+  });
 });

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

@@ -13,21 +13,41 @@ export const doc = {
   type: 'command',
   name: 'template',
   displayName: 'astryx template',
-  namespace: 'cli',
-  summary: 'Inject a page or block template',
+  namespace: 'cli/commands',
+  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 ' +
-    'into the project at a target path. Narrow an ambiguous name with --type and/or --package. ' +
-    '--cdn writes the no-build-step CDN starter page, which ships as an asset rather than as ' +
-    'a discovered template.',
+    'into the project at a target path. A configured integration replacement is the ' +
+    'default for its Core id; use --package @astryxdesign/core for the original. ' +
+    'Narrow other ambiguous names with --type and/or --package. --cdn writes the ' +
+    'no-build-step CDN starter page, which ships as an asset rather than as a ' +
+    'discovered template.',
   fn: 'template',
   args: [
-    {name: 'name', param: 'name', required: false},
-    {name: 'path', param: 'options.targetPath', required: false},
+    {
+      name: 'name',
+      param: 'name',
+      required: false,
+      description: 'Template id (see --list). Omit it to list the templates.',
+    },
+    {
+      name: 'path',
+      param: 'options.targetPath',
+      required: false,
+      description:
+        'Where to scaffold the template, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
+        "any other path is a directory, which receives page.tsx for a page template or the block's own file name for a block. " +
+        'Omit it to print the source.',
+    },
   ],
   options: [
-    {flag: '--list', param: 'options.list', description: 'List available templates'},
+    {
+      flag: '--list',
+      param: 'options.list',
+      description:
+        'List available templates (narrow with --type and --package) and do nothing else: <name>, <path>, --skeleton and --overwrite are ignored',
+    },
     {
       flag: '--type <type>',
       param: 'options.type',
@@ -37,37 +57,56 @@ export const doc = {
     {
       flag: '--package <pkg>',
       param: 'options.package',
-      description: 'Narrow to templates from a specific package',
+      description:
+        'Narrow to templates from a specific package. Use @astryxdesign/core to select an original hidden by an integration replacement.',
     },
     {
       flag: '--skeleton',
       param: 'options.skeleton',
       description:
-        'Show layout skeleton with spatial annotations (padding, gap, nesting)',
+        'Show layout skeleton with spatial annotations (padding, gap, nesting) instead of the source. Needs <name>. ' +
+        'It writes nothing, so <path> and --overwrite are ignored; --list and --cdn take precedence',
     },
     {
       flag: '--cdn [path]',
       param: 'options.cdn',
       description:
-        'Write the no-build-step CDN starter page (default: cdn.template.html)',
+        'Write the no-build-step CDN starter page and do nothing else: <name>, --list, --skeleton, --type and --package are ignored. ' +
+        'The page goes to the --cdn value, else to <path>, else cdn.template.html, and that path is always the file itself. ' +
+        'A value right after --cdn (anything not starting with -) is taken as that path',
     },
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Overwrite existing files without prompting',
+      description:
+        'Replace an existing target file. Without it an existing file is refused (ERR_FILE_EXISTS) and an existing CDN page is left as is',
     },
   ],
   examples: [
     {label: 'List templates', cli: 'astryx template --json'},
+    {
+      label: 'List exact Core ids',
+      cli: 'astryx --json template --list --package @astryxdesign/core',
+    },
     {
       label: 'Scaffold into the app',
       cli: 'astryx template dashboard ./src/app',
     },
+    {
+      label: 'Select a replaced Core original',
+      cli: 'astryx template shell-side-nav ./src/app --package @astryxdesign/core',
+    },
     {label: 'CDN starter page', cli: 'astryx template --cdn'},
-    {label: 'CDN starter page, elsewhere', cli: 'astryx template --cdn public/demo.html'},
+    {
+      label: 'CDN starter page, elsewhere',
+      cli: 'astryx template --cdn public/demo.html',
+    },
   ],
   exitCodes: [
-    {code: 0, when: 'success, including a CDN page left untouched because it already exists'},
+    {
+      code: 0,
+      when: 'success, including a CDN page left untouched because it already exists',
+    },
     {
       code: 1,
       when: 'unknown or ambiguous template, no source, a path escape, or an existing target without --overwrite',

package/clients/cli/commands/template.flag-help.test.mjs

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx template` documents which of its flags win when they are
+ * combined, and behaves as documented. Option text is read from the generated
+ * manifest, the same strings `--help` prints.
+ */
+
+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';
+
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-flags-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} rel */
+const exists = rel => fs.existsSync(path.join(tmpDir, rel));
+
+/** Files in the project, ignoring package.json. */
+const written = () => fs.readdirSync(tmpDir).filter(f => f !== 'package.json');
+
+/**
+ * template's option descriptions from the manifest, keyed by long flag.
+ * @returns {Promise<Record<string, string>>}
+ */
+async function templateOptions() {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  const template = JSON.parse(stdout).data.commands.find(
+    (/** @type {{name: string}} */ c) => c.name === 'template',
+  );
+  return Object.fromEntries(
+    template.options.map((/** @type {{flag: string, description: string}} */ o) => [
+      o.flag.match(/--[a-z-]+/)?.[0],
+      o.description,
+    ]),
+  );
+}
+
+/** @param {string[]} args */
+async function templateJson(args) {
+  const result = await runCli(['--json', 'template', ...args], tmpDir);
+  return {status: result.status, envelope: JSON.parse(result.stdout)};
+}
+
+describe('astryx template flag precedence', () => {
+  it('--list: help says <name>, <path>, --skeleton and --overwrite are ignored, and they are', async () => {
+    const help = (await templateOptions())['--list'];
+    for (const ignored of ['<name>', '<path>', '--skeleton', '--overwrite']) {
+      expect(help).toContain(ignored);
+    }
+    expect(help).toMatch(/are ignored/);
+
+    const {status, envelope} = await templateJson([
+      'dashboard',
+      './src/page.tsx',
+      '--list',
+      '--skeleton',
+      '--overwrite',
+    ]);
+    expect(status).toBe(0);
+    expect(envelope.type).toBe('template.list');
+    expect(written()).toEqual([]);
+  }, SLOW);
+
+  it('--skeleton: help says it needs <name> and writes nothing, and it does', async () => {
+    const help = (await templateOptions())['--skeleton'];
+    expect(help).toMatch(/Needs <name>/);
+    expect(help).toMatch(/writes nothing, so <path> and --overwrite are ignored/);
+    expect(help).toMatch(/--list and --cdn take precedence/);
+
+    const shown = await templateJson(['dashboard', './src/page.tsx', '--skeleton', '--overwrite']);
+    expect(shown.status).toBe(0);
+    expect(shown.envelope.type).toBe('template.skeleton');
+    expect(written()).toEqual([]);
+
+    const nameless = await templateJson(['--skeleton']);
+    expect(nameless.status).toBe(1);
+    expect(nameless.envelope.code).toBe('ERR_UNKNOWN_TEMPLATE');
+  }, SLOW);
+
+  it('--cdn: help says it overrides everything and where the page goes, and the CLI does that', async () => {
+    const help = (await templateOptions())['--cdn'];
+    for (const ignored of ['<name>', '--list', '--skeleton', '--type', '--package']) {
+      expect(help).toContain(ignored);
+    }
+    expect(help).toMatch(/--cdn value, else to <path>, else cdn\.template\.html/);
+    expect(help).toMatch(/always the file itself/);
+    expect(help).toMatch(/value right after --cdn/);
+
+    const everything = await templateJson(['dashboard', '--list', '--skeleton', '--type', 'bogus', '--cdn']);
+    expect(everything.envelope.type).toBe('template.cdn');
+    expect(everything.envelope.data.path).toBe('cdn.template.html');
+
+    // A bare --cdn writes to <path>, and a path with no extension is still the file.
+    const positional = await templateJson(['dashboard', 'demo', '--cdn']);
+    expect(positional.envelope.data.path).toBe('demo');
+    expect(fs.statSync(path.join(tmpDir, 'demo')).isFile()).toBe(true);
+
+    // The word after --cdn is its value, not the template name.
+    const value = await templateJson(['--cdn', 'dashboard']);
+    expect(value.envelope.data.path).toBe('dashboard');
+    expect(exists('dashboard')).toBe(true);
+  }, SLOW);
+});

package/clients/cli/commands/template.mjs

@@ -4,12 +4,9 @@
  * @file template command — thin CLI wrapper around api/template.mjs
  */
 
-import * as path from 'node:path';
-import * as fs from 'node:fs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {emit, section, text, records, code} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {template as templateApi} from '../../../api/template/template.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
@@ -21,18 +18,6 @@ import {doc as templateFn} from '../../../api/template/template.doc.mjs';
 
 export {discoverTemplates, listTemplates} from '../../../api/template/template.mjs';
 
-/**
- * A template entry as produced by the discover* helpers in api/template.mjs.
- * The api layer returns these as `object[]`; this local shape captures the
- * fields the command consumes. Remove once api/template.mjs exports a precise
- * type for its discovered templates.
- * @typedef {object} DiscoveredTemplate
- * @property {'page' | 'block'} type
- * @property {string} dirName
- * @property {string} name
- * @property {string} filePath
- */
-
 /**
  * The discriminated response returned by the template API. The api layer
  * currently declares `{type: string, data: unknown}`; narrow it here to the
@@ -89,36 +74,11 @@ export function registerTemplate(program) {
       // doctor integration validate. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(
-          /** @type {Array<import('../../../foundation/integrations/integrations.mjs').LoadedIntegration>} */ (
-            project.loadedIntegrations
-          ),
-          {json},
-        );
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
 
-      // Pre-flight overwrite check (only when we'd actually copy a file).
-      // The API resolves the destination; we need to mirror its logic
-      // narrowly enough to detect collisions before invoking it.
-      if (
-        name &&
-        targetPath &&
-        !options.list &&
-        !options.skeleton &&
-        !options.cdn
-      ) {
-        const collision = await detectTemplateCollision(name, targetPath);
-        if (collision && !options.overwrite) {
-          const rel = path.relative(process.cwd(), collision) || collision;
-          const msg =
-            `Refusing to overwrite existing file ${rel}. ` +
-            `Re-run with --overwrite (or -f) to replace it.`;
-          return cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-        }
-      }
-
       /** @type {TemplateResponse} */
       let result;
       try {
@@ -156,12 +116,14 @@ export function registerTemplate(program) {
           // isn't the built-in core package.
           /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry} t */
           const toRow = t => ({
+            id: t.id,
             name: t.isReady ? t.name : `${t.name} (WIP)`,
             description: t.description,
             package:
               t.package && t.package !== '@astryxdesign/core' ? t.package : '',
+            replaces: t.replaces ?? '',
           });
-          const fields = ['name', 'description', 'package'];
+          const fields = ['id', 'name', 'description', 'package', 'replaces'];
           emit(
             pages.length > 0 && section('Page Templates'),
             pages.length > 0 && records(pages.map(toRow), {fields}),
@@ -229,52 +191,3 @@ export function registerTemplate(program) {
     },
   });
 }
-
-/**
- * Mirror the destination-resolution logic in api/template.mjs so we can
- * detect a clobber before invoking the API.
- *
- * Returns the absolute destination file path if it already exists, or
- * `null` otherwise (template missing, no collision, or list/skeleton mode).
- *
- * Path-safety enforcement happens inside the API; here we only need
- * enough precision to check existence — a false negative just means the
- * API will catch the issue and abort.
- *
- * @param {string} name
- * @param {string} targetPath
- * @returns {Promise<string | null>}
- */
-async function detectTemplateCollision(name, targetPath) {
-  const {discoverTemplates} = await import('../../../api/template/template.mjs');
-  /** @type {DiscoveredTemplate[]} */
-  let templates;
-  try {
-    templates = /** @type {DiscoveredTemplate[]} */ (
-      await discoverTemplates(process.cwd())
-    );
-  } catch {
-    return null;
-  }
-  const match = templates.find(t => t.dirName === name);
-  if (!match) return null;
-
-  // Resolve target as the API will. We can't call assertWithin here
-  // because the API does it itself; we just need to know "is there a
-  // file at the destination?".
-  const resolved = path.resolve(process.cwd(), targetPath);
-
-  // File-arg branch: targetPath looks like `./foo.tsx`.
-  const {isFilePathArg} = await import('../../../foundation/fs/path-safety.mjs');
-  let dest;
-  if (isFilePathArg(targetPath)) {
-    dest = resolved;
-  } else {
-    const fileName = match.type === 'block'
-      ? path.basename(match.filePath)
-      : 'page.tsx';
-    dest = path.join(resolved, fileName);
-  }
-
-  return fs.existsSync(dest) ? dest : null;
-}

package/clients/cli/commands/template.path-help.test.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `template <name> <path>` decides by extension whether <path> is the
+ * file to write or a directory to write into. Help and the manifest say so,
+ * and every extension they list is one the resolver treats as a file.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
+
+const SLOW = 30_000;
+
+/** @param {string} text */
+const listedExtensions = text =>
+  [...(text.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)].map(m => m[0]);
+
+describe('template path resolution is documented', () => {
+  it('help explains the file-or-directory rule and the default file names', async () => {
+    const {status, stdout} = await runCli(['template', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Arguments:/);
+    expect(stdout).toContain('page.tsx');
+    expect(stdout).toMatch(/block's own file name/);
+  }, SLOW);
+
+  it('the manifest carries the same description, and its extensions are the resolver\'s', async () => {
+    const {stdout} = await runCli(['manifest', '--json']);
+    const {data} = JSON.parse(stdout);
+    const template = data.commands.find((/** @type {any} */ c) => c.name === 'template');
+    const pathArg = template.arguments.find((/** @type {any} */ a) => a.name === 'path');
+    expect(pathArg.description).toContain('page.tsx');
+
+    const exts = listedExtensions(pathArg.description);
+    expect(exts.length).toBeGreaterThan(0);
+    for (const ext of exts) expect(isFilePathArg(`out/page${ext}`)).toBe(true);
+    expect(isFilePathArg('out/page')).toBe(false);
+  }, SLOW);
+});