Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): state which template flags win when combined (#6591)

Joey109554a36f7c
diff --git a/.changeset/cli-spec-template-flag-interactions.md b/.changeset/cli-spec-template-flag-interactions.md
new file mode 100644
index 0000000000..bfbbffaed5
--- /dev/null
+++ b/.changeset/cli-spec-template-flag-interactions.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] `astryx template --help` and the manifest now say which flags win when they are combined: `--cdn` overrides everything else and writes to its value, else to `<path>`, else `cdn.template.html`; `--list` ignores a name, a path, `--skeleton` and `--overwrite`; and `--skeleton` needs a name and writes nothing.
+
+@josephfarina
diff --git a/packages/cli/clients/cli/commands/template.doc.mjs b/packages/cli/clients/cli/commands/template.doc.mjs
index 4ee6c4fd2e..f13d8697b5 100644
--- a/packages/cli/clients/cli/commands/template.doc.mjs
+++ b/packages/cli/clients/cli/commands/template.doc.mjs
@@ -40,7 +40,12 @@ export const doc = {
},
],
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',
@@ -56,13 +61,16 @@ export const doc = {
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',
diff --git a/packages/cli/clients/cli/commands/template.flag-help.test.mjs b/packages/cli/clients/cli/commands/template.flag-help.test.mjs
new file mode 100644
index 0000000000..17e2554a07
--- /dev/null
+++ b/packages/cli/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);
+});