@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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

@@ -13,21 +13,41 @@ export const doc = {
   type: 'command',
   name: 'template',
   displayName: 'astryx template',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Inject a page or block template',
   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);
+});