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

package/clients/cli/commands/build-theme.variants.test.mjs

@@ -324,6 +324,82 @@ describe('theme build custom-variant augmentations', () => {
     );
   });
 
+  it('rejects a custom Heading type whose only declaration is blank', async () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: { heading: { 'type:hero': { fontSize: '' } } },
+      };\n`,
+    );
+
+    const result = await runCli(
+      ['theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain(
+      'Custom Heading type "hero" needs a non-empty standalone',
+    );
+    expect(fs.existsSync(path.join(tmpDir, 'variants-theme.css'))).toBe(false);
+  });
+
+  it('rejects a custom Heading type whose every declaration the compiler drops', async () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: {
+          heading: { 'type:hero': { color: 'red; } body { color: blue' } },
+        },
+      };\n`,
+    );
+
+    const result = await runCli(
+      ['--json', 'theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+
+    expect(result.code).toBe(1);
+    const envelope = JSON.parse(result.stdout);
+    expect(envelope.code).toBe('ERR_THEME_INVALID');
+    expect(envelope.error).toContain('Custom Heading type "hero"');
+    expect(fs.existsSync(path.join(tmpDir, 'variants-theme.css'))).toBe(false);
+    expect(
+      fs.existsSync(path.join(tmpDir, 'variants-theme.variants.d.ts')),
+    ).toBe(false);
+  });
+
+  it('builds a custom Heading type that keeps one valid declaration', async () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: {
+          heading: {
+            'type:hero': { fontSize: '80px', color: 'red; } body { color: blue' },
+          },
+        },
+      };\n`,
+    );
+
+    const result = await runCli(
+      ['--json', 'theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+
+    expect(result.code).toBe(0);
+    const envelope = JSON.parse(result.stdout);
+    expect(envelope.data.outputs.variantsDts).toBe(
+      'variants-theme.variants.d.ts',
+    );
+    expect(envelope.data.warnings.join('\n')).toContain('Declaration dropped');
+  });
+
   it('makes generated custom component prop values type-check through public subpaths', async () => {
     const themeFile = writeTheme(
       tmpDir,

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

@@ -12,13 +12,14 @@ export const doc = {
   type: 'command',
   name: 'build',
   displayName: 'astryx build',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
-    'Build a page: composition kit for an idea, or the workflow playbook (no args)',
+    'Build a page: the template to start from, or the workflow playbook (no query)',
   description:
-    'The assemble-a-page entry point. With no query it returns the how-to-build-a-page ' +
-    'playbook; with a query it groups the unified search hits into a composition kit: ' +
-    'the closest templates, drop-in blocks, and idea-specific components and hooks.',
+    'The build-a-page entry point. With no query it returns the how-to-build-a-page ' +
+    'playbook; with a query it names the page template to start from (always one: the ' +
+    'closest page template, or the app shell when none matches), the next two templates, and the ' +
+    'drop-in blocks and idea-specific components and hooks around it.',
   fn: 'build',
   args: [{name: 'query', param: 'query', required: false}],
   options: [
@@ -35,16 +36,23 @@ export const doc = {
     },
     {
       flag: '--verbose',
-      description: 'Verbose output (include import paths and match reason)',
+      description:
+        'Verbose output (every block and component, full descriptions, import paths and match reason)',
     },
   ],
   examples: [
     {label: 'Get the playbook', cli: 'astryx build'},
-    {label: 'Compose a page', cli: 'astryx build "analytics dashboard" --json'},
+    {
+      label: 'Find the template to start from',
+      cli: 'astryx build "analytics dashboard" --json',
+    },
   ],
   exitCodes: [
     {code: 0, when: 'success (including zero matches)'},
-    {code: 1, when: 'invalid --type or a non-positive --limit'},
+    {
+      code: 1,
+      when: 'invalid --type, a non-positive --limit, or a query when @astryxdesign/core cannot be found (the playbook needs no core)',
+    },
   ],
   related: ['search', 'template', 'component', 'hook', 'init'],
 };

package/clients/cli/commands/build.exit-codes-doc.test.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx build` documents that a query needs @astryxdesign/core while
+ * the playbook does not, and exits as documented without it.
+ */
+
+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 {doc as buildDoc} from './build.doc.mjs';
+
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-no-core-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {number} code */
+const exitWhen = code => buildDoc.exitCodes?.find(e => e.code === code)?.when ?? '';
+
+describe('astryx build without @astryxdesign/core', () => {
+  it('the CommandDoc lists a query without core under exit 1, and both modes exit 1', async () => {
+    expect(exitWhen(1)).toMatch(/a query when @astryxdesign\/core cannot be found/);
+
+    const text = await runCli(['build', 'dashboard'], tmpDir);
+    const json = await runCli(['--json', 'build', 'dashboard'], tmpDir);
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+    expect(JSON.parse(json.stdout).error).toMatch(/@astryxdesign\/core/);
+  }, SLOW);
+
+  it('the CommandDoc says the playbook needs no core, and it exits 0', async () => {
+    expect(exitWhen(1)).toMatch(/the playbook needs no core/);
+
+    const {status, stdout} = await runCli(['--json', 'build'], tmpDir);
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).type).toBe('build.help');
+  }, SLOW);
+});

package/clients/cli/commands/build.mjs

@@ -4,8 +4,9 @@
  * @file build command — thin wrapper with a stable result summary.
  *
  *   astryx build                  → the PLAYBOOK (how to build a page)
- *   astryx build "<what>"         → a COMPOSITION KIT (closest page template,
- *                                   blocks, components) with a recommended START.
+ *   astryx build "<what>"         → the TEMPLATE to start from (always one: the
+ *                                   closest page, or the app shell), other
+ *                                   templates, then blocks and components.
  *
  * All grouping/scoring lives in api/build; this file only parses flags and
  * renders. Command strings are prefixed for the caller's package manager here
@@ -22,57 +23,45 @@ import {
   emit,
   section,
   text,
+  list,
   record,
   records,
-  ARROW,
 } from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
+import {firstSentence} from '../../../foundation/text/string-utils.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {build as buildApi} from '../../../api/build/build.mjs';
 import {doc as buildCommand} from './build.doc.mjs';
 import {doc as buildFn} from '../../../api/build/build.doc.mjs';
 
 /**
- * Emit the build playbook (shown when `build` is run with no query).
- * @param {string} run - The CLI invocation prefix (e.g. `npx astryx`).
+ * Playbook commands as records whose field names are the JSON keys, so a
+ * reader can grep `^command:`. The command is run with the caller's invocation.
+ * @type {import('../formatters/index.mjs').RecordOptions}
  */
-function printPlaybook(run) {
+const COMMAND_RECORDS = {
+  fields: ['command', 'purpose'],
+  format: {command: command => formatCliCommand(command)},
+};
+
+/**
+ * Emit the build playbook (shown when `build` is run with no query) — a
+ * projection of the `build.help` data, so text and JSON carry the same steps.
+ * @param {import('../../../api/build/build.type.mjs').BuildHelpResponse['data']} playbook
+ */
+function printPlaybook(playbook) {
   emit(
-    section('How to build a page with Astryx'),
-    text(
-      [
-        "1. Find a starting point for what you're building:",
-        `     ${run} build "<what you're building>"`,
-        `   ${ARROW} returns the closest [page] template, the [block]s that cover parts,`,
-        '     and the [component]s to fill the gaps, with a "Compose:" suggestion.',
-      ].join('\n'),
-    ),
-    text(
-      [
-        `2. If a [page] template matches ${ARROW} scaffold it and adapt:`,
-        `     ${run} template <name> [path]`,
-      ].join('\n'),
-    ),
-    text(
-      [
-        `3. If nothing matches exactly ${ARROW} compose:`,
-        `     ${run} template <name> --skeleton   # study a close page's layout`,
-        `     ${run} template <BlockName>         # drop in each block from the kit`,
-        `     ${run} component <Name>             # fill remaining gaps (read props)`,
-      ].join('\n'),
-    ),
-    text(
-      [
-        '4. Rules (keep it on-system):',
-        '   - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
-        `   - No style={{}} — use component props; design tokens via \`${run} docs tokens\`.`,
-        '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
-      ].join('\n'),
-    ),
-    text(
-      `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral ` +
-        `lookup of any component/doc/template, use \`${run} search <query>\`.`,
-    ),
+    section(playbook.title),
+    ...playbook.steps.flatMap((step, i) => [
+      section(`${i + 1}. ${step.title}`),
+      records(step.commands, COMMAND_RECORDS),
+      step.returns ? record({returns: step.returns}) : null,
+    ]),
+    section(`${playbook.steps.length + 1}. Rules (keep it on-system)`),
+    list(playbook.rules),
+    ...(playbook.related.length > 0
+      ? [section('Related'), records(playbook.related, COMMAND_RECORDS)]
+      : []),
   );
 }
 
@@ -91,7 +80,10 @@ export function registerBuild(program) {
 
       // No query → the playbook. Still routed through the API for the envelope.
       if (!query || !String(query).trim()) {
-        const result = await buildApi(undefined, {cwd: process.cwd()});
+        const result =
+          /** @type {import('../../../api/build/build.type.mjs').BuildHelpResponse} */ (
+            await buildApi(undefined, {cwd: process.cwd()})
+          );
         // The playbook is a document, not a lookup: one doc, always the same
         // one. Counting it as a result keeps "what did this run answer with"
         // true for the no-argument form too.
@@ -100,7 +92,7 @@ export function registerBuild(program) {
           jsonOut(result);
           return playbook;
         }
-        printPlaybook(run);
+        printPlaybook(result.data);
         return playbook;
       }
 
@@ -136,6 +128,7 @@ export function registerBuild(program) {
         hasResults,
         matchCount,
         directMatch,
+        start,
         pages,
         blocks,
         domain,
@@ -144,8 +137,8 @@ export function registerBuild(program) {
         hint,
       } = result.data;
       // The kit spans domains, so its kind comes from the pieces themselves.
-      // `frame` and `foundation` are always-on and deliberately excluded: they
-      // are not what the query matched.
+      // `start` (which may be the fallback shell), `frame` and `foundation`
+      // are deliberately excluded: they are not what the query matched.
       const answered = resultSetOf([...pages, ...blocks, ...domain], {
         count: matchCount,
         empty: !hasResults,
@@ -158,7 +151,7 @@ export function registerBuild(program) {
         return answered;
       }
 
-      if (!hasResults) {
+      if (!hasResults && !start) {
         emit(
           text(`No matches for "${q}".`),
           text(`Try a broader term, or browse: ${run} component --list`),
@@ -166,97 +159,127 @@ export function registerBuild(program) {
         return answered;
       }
 
-      // Same JSON->text projection as search, but leaner: the section header
-      // already says the kind, so drop `domain`/`import` by default (they're in
-      // --json and under --verbose). Keeps each item to name/displayName/desc/cmd.
-      const fields = options.verbose
-        ? [
-            'name',
-            'domain',
-            'displayName',
-            'score',
-            'reason',
-            'import',
-            'description',
-            'command',
-          ]
-        : ['name', 'displayName', 'description', 'command'];
+      // Four sections, one job each: the TEMPLATE to scaffold, OTHER
+      // TEMPLATES if its layout is wrong, BLOCKS for parts it lacks, and
+      // COMPONENTS for the rest. Descriptions stop at their first sentence and
+      // blocks and components share one command line in their heading; the
+      // JSON and --verbose carry everything.
+      const verbose = Boolean(options.verbose);
       /** @type {import('../formatters/index.mjs').RecordOptions} */
-      const recordOpts = {fields, format: {command: formatCliCommand}};
-
-      // `template <name> <path>` scaffolds into your project; <path> is the file
-      // (or folder) to write it to — a placeholder, since we can't know your
-      // layout. `--skeleton` and `component <Name>` just print, so no path.
-      const startCmd = directMatch
-        ? `${run} template ${pages[0].name} <path>`
-        : pages.length
-          ? `${run} template ${pages[0].name} --skeleton`
-          : `${run} component AppShell`;
-      const startNote = directMatch
-        ? `This \`${pages[0].name}\` page template appears to be the closest to what you want, so we recommend scaffolding it into your project — replace \`<path>\` with the file (or folder) to write it to — then adapting. Otherwise, browse PAGE TEMPLATES first, then BLOCKS and DOMAIN COMPONENTS below.`
-        : pages.length
-          ? `No exact match, but \`${pages[0].name}\` is the closest page template — run the above to print its layout as a reference, then compose. Otherwise, browse PAGE TEMPLATES first, then BLOCKS and DOMAIN COMPONENTS below.`
-          : 'No page template fits — frame with AppShell, then compose from BLOCKS and DOMAIN COMPONENTS below.';
-
-      // A short legend up top: what this output is, how to use it, and the exact
-      // order of the sections below (only the ones actually present) so it reads
-      // clearly and parses predictably.
-      const sectionsOrder = ['RECOMMENDED START'];
-      if (pages.length) sectionsOrder.push('PAGE TEMPLATES');
-      if (blocks.length) sectionsOrder.push('BLOCKS');
-      if (domain.length) sectionsOrder.push('DOMAIN COMPONENTS');
-      sectionsOrder.push('FRAME + FOUNDATION');
-      // The legend promises the complete order, so a section emitted after it
-      // has to be in it.
-      if (hint) sectionsOrder.push('FEW MATCHES');
+      const full = {
+        fields: [
+          'name',
+          'domain',
+          'displayName',
+          'score',
+          'reason',
+          'import',
+          'description',
+          'command',
+        ],
+        format: {command: formatCliCommand},
+      };
+      /** @param {string[]} fields */
+      const brief = fields => ({
+        fields,
+        format: {command: formatCliCommand, description: firstSentence},
+      });
+      // Blocks and components are extras: the text names the top few, and
+      // says how many more the JSON and --verbose carry.
+      const TOP = 3;
+      /** @param {unknown[]} items */
+      const shown = items => (verbose ? items : items.slice(0, TOP));
+      /** @param {unknown[]} items */
+      const more = items =>
+        !verbose && items.length > TOP
+          ? ` (top ${TOP} of ${items.length}; --verbose for all)`
+          : '';
 
       /** @type {import('../formatters/index.mjs').Block[]} */
       const out = [
         section(`Build kit for "${q}"`),
         text(
-          'A recommended set of pieces to assemble this page, in the order to use them. ' +
-            'Begin with RECOMMENDED START, then pull from the sections below — each ' +
-            'recommended item includes a `command:` to run next.\n' +
-            `Sections in order: ${sectionsOrder.join(', ')}.`,
+          start
+            ? 'Start from the TEMPLATE, fill it with BLOCKS, and use COMPONENTS only for what is left.\n' +
+                'Changing a page you already have? Keep it, and use only the blocks and components.'
+            : 'This kit is narrowed by --type, so it names no template.',
         ),
-        section('RECOMMENDED START', `${startNote}\n${startCmd}`),
       ];
 
-      if (pages.length) {
+      if (start) {
         out.push(
           section(
-            'PAGE TEMPLATES',
-            directMatch
-              ? 'Closest full-page templates — scaffold one, then adapt it.'
-              : 'Closest full-page templates — use as a layout reference.',
+            'TEMPLATE',
+            `${start.reason} ${
+              start.basis === 'fallback'
+                ? 'Scaffold it, then put blocks inside it.'
+                : 'Scaffold it, then replace its content. Keep its layout and spacing.'
+            }`,
+          ),
+          record(
+            start,
+            verbose
+              ? {
+                  fields: ['name', 'displayName', 'description', 'command'],
+                  format: {command: formatCliCommand},
+                }
+              : brief(['name', 'description', 'command']),
           ),
-          records(pages, recordOpts),
         );
+        if (start.alternatives.length) {
+          out.push(
+            section(
+              'OTHER TEMPLATES',
+              `If the layout is wrong, scaffold one of these instead. All page templates: ${formatCliCommand('template --list --type page')}`,
+            ),
+            records(
+              start.alternatives,
+              verbose ? full : brief(['name', 'description', 'command']),
+            ),
+          );
+        }
       }
-      if (blocks.length) {
+      // Search's own page matches, so the text carries every field the JSON
+      // does: one line by default, the full entries under --verbose.
+      if (pages.length) {
         out.push(
-          section('BLOCKS', 'Drop-in patterns that cover parts of the page.'),
-          records(blocks, recordOpts),
+          verbose
+            ? section(
+                'SEARCH MATCHES',
+                'Page templates keyword search matched, best first.',
+              )
+            : text(
+                `Keyword search matched these page templates: ${pages.map(p => p.name).join(', ')}.`,
+              ),
         );
+        if (verbose) out.push(records(pages, full));
       }
-      if (domain.length) {
+      if (blocks.length) {
         out.push(
-          section('DOMAIN COMPONENTS', 'Components specific to this idea.'),
-          records(domain, recordOpts),
+          section(
+            'BLOCKS',
+            `Ready-made sections for parts the template lacks${more(blocks)}. Print one: ${formatCliCommand('template <name>')}`,
+          ),
+          records(
+            shown(blocks),
+            verbose ? full : brief(['name', 'description']),
+          ),
         );
       }
-
       out.push(
         section(
-          'FRAME + FOUNDATION',
-          'Always-available shell + layout/text/action primitives.',
+          'COMPONENTS',
+          `For what the template and blocks do not cover${more(domain)}. Read one: ${formatCliCommand('component <name>')}`,
         ),
-        record({
-          frame,
-          foundation,
-          setup:
-            'import "@astryxdesign/core/reset.css" + "astryx.css"; no <div>/style for layout — use Stack/Grid + tokens',
-        }),
+        ...(domain.length
+          ? [
+              records(
+                shown(domain),
+                verbose ? full : brief(['name', 'description']),
+              ),
+            ]
+          : []),
+        record({frame, foundation}),
       );
 
       // Last, so it is the line the reader leaves with — and only when the kit

package/clients/cli/commands/build.playbook.test.mjs

@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The no-query `build` playbook is data. `--json` carries every step,
+ * rule and command; the text output is rendered from those values and shows
+ * nothing the envelope lacks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {program} from '../index.mjs';
+
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const SLOW = 30_000;
+
+/** @param {string} s */
+const ascii = s => s.replace(/[\u2014\u2013]/g, '-');
+
+describe('build playbook: text is a projection of the JSON', () => {
+  it('prints exactly the commands, steps and rules the envelope carries', async () => {
+    const json = await runCli(['build', '--json'], REPO);
+    expect(json.status).toBe(0);
+    const {type, data} = JSON.parse(json.stdout);
+    expect(type).toBe('build.help');
+    expect(data.steps.length).toBeGreaterThan(0);
+    expect(data.rules.length).toBeGreaterThan(0);
+
+    const human = await runCli(['build'], REPO);
+    expect(human.status).toBe(0);
+    const out = human.stdout;
+
+    expect(out).toContain(ascii(data.title));
+    for (const step of data.steps) {
+      expect(out).toContain(ascii(step.title));
+      if (step.returns) expect(out).toContain(ascii(step.returns));
+    }
+    for (const rule of data.rules) expect(out).toContain(ascii(rule));
+
+    /** @type {Array<{command: string, purpose?: string}>} */
+    const commands = [
+      ...data.steps.flatMap((/** @type {any} */ s) => s.commands),
+      ...data.related,
+    ];
+    // Each command is one record whose field names are the JSON keys:
+    // `command:` (run with the caller's invocation), then `purpose:`.
+    const printed = out
+      .split('\n')
+      .filter(line => line.startsWith('command: '))
+      .map(line => line.slice('command: '.length).trim());
+    expect(printed).toHaveLength(commands.length);
+    commands.forEach(({command, purpose}, i) => {
+      expect(printed[i].endsWith(` ${command}`)).toBe(true);
+      if (purpose) expect(out).toContain(`purpose: ${ascii(purpose)}`);
+    });
+    // No column the handler drew itself.
+    expect(out).not.toMatch(/ {2,}# /);
+  }, SLOW);
+
+  it('names only commands this CLI registers', async () => {
+    const {stdout} = await runCli(['build', '--json'], REPO);
+    const {data} = JSON.parse(stdout);
+    const registered = new Set(program.commands.map(c => c.name()));
+    const commands = [
+      ...data.steps.flatMap((/** @type {any} */ s) => s.commands),
+      ...data.related,
+    ];
+    expect(commands.length).toBeGreaterThan(0);
+    for (const {command} of commands) {
+      expect(registered.has(command.split(' ')[0])).toBe(true);
+    }
+  }, SLOW);
+});