@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/clients/cli/commands/build-theme.ascii-output.test.mjs

@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Human output of the `theme` command group stays plain ASCII.
+ *
+ * Covers every theme-build line family that carried a glyph or typographic
+ * punctuation: success, warning, error, notice, and font-help lines of a
+ * standalone build; `--check` in both states; a batch build and check; a
+ * family build and check; the quoted-glob suggestion; and a palette preview.
+ * Each case also asserts its ASCII marker, so a line that stops printing
+ * cannot pass the ASCII check vacuously.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+// Under the CLI package so fixtures resolve `@astryxdesign/core/theme`.
+const CLI_ROOT = path.resolve(import.meta.dirname, '../../..');
+
+const OCEAN = `import {defineTheme} from '@astryxdesign/core/theme';
+export const oceanTheme = defineTheme({
+  name: 'ocean',
+  typography: {body: {family: 'Inter'}},
+  tokens: {'--color-background-body': '#ffffff'},
+  components: {
+    progressbar: {base: {color: 'red'}},
+    button: {base: {'--_button-radius': '2px'}},
+  },
+});
+`;
+const CALM = `import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from './ocean.mjs';
+export const oceanCalmTheme = defineTheme({
+  name: 'ocean-calm',
+  extends: oceanTheme,
+  tokens: {'--color-background-body': '#eeeeee'},
+});
+`;
+
+/** @type {string} */
+let dir;
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(CLI_ROOT, '.tmp-theme-ascii-'));
+  fs.writeFileSync(path.join(dir, 'package.json'), '{"type":"module"}\n');
+  fs.writeFileSync(path.join(dir, 'ocean.mjs'), OCEAN);
+  fs.writeFileSync(path.join(dir, 'ocean-calm.mjs'), CALM);
+});
+
+afterEach(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** @param {{stdout: string, stderr: string}} result */
+function nonAscii(result) {
+  return [
+    ...new Set(`${result.stdout}${result.stderr}`.match(/[\u0080-\uffff]/g)),
+  ];
+}
+
+/** @param {string[]} args */
+function run(args) {
+  return runCli(['theme', ...args], dir);
+}
+
+describe('theme command human output is plain ASCII', () => {
+  it('a standalone build: ok, warning, error, notice, and font help lines', async () => {
+    const result = await run(['build', 'ocean.mjs']);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('[ok] ocean.css');
+    expect(result.stderr).toContain('[warn] Deprecated component target');
+    expect(result.stderr).toContain('[error] Component "button"');
+    expect(result.stdout).toContain('note: Font "Inter"');
+    expect(result.stdout).toContain('[note] Theme "ocean" names fonts');
+    expect(nonAscii(result)).toEqual([]);
+  });
+
+  it('--check, up to date and stale', async () => {
+    await run(['build', 'ocean.mjs']);
+    const upToDate = await run(['build', 'ocean.mjs', '--check']);
+    expect(upToDate.code).toBe(0);
+    expect(upToDate.stdout).toContain('[ok] Theme outputs are up to date');
+    expect(nonAscii(upToDate)).toEqual([]);
+
+    fs.appendFileSync(path.join(dir, 'ocean.css'), '/* drift */\n');
+    const stale = await run(['build', 'ocean.mjs', '--check']);
+    expect(stale.code).toBe(1);
+    expect(stale.stderr).toContain('[fail] 1 theme output(s) are out of date');
+    expect(nonAscii(stale)).toEqual([]);
+  });
+
+  it('a batch build and check', async () => {
+    const built = await run(['build', 'ocean.mjs', 'ocean-calm.mjs']);
+    expect(built.code).toBe(0);
+    expect(built.stdout).toContain('[ok] Built 2 themes.');
+    expect(nonAscii(built)).toEqual([]);
+
+    const checked = await run([
+      'build',
+      'ocean.mjs',
+      'ocean-calm.mjs',
+      '--check',
+    ]);
+    expect(checked.code).toBe(0);
+    expect(checked.stdout).toContain('[ok] Checked 2 themes.');
+    expect(nonAscii(checked)).toEqual([]);
+  });
+
+  it('a family build and a stale family check', async () => {
+    const familyArgs = [
+      'build',
+      '--family',
+      'ocean.mjs',
+      'ocean-calm.mjs',
+      '--family-key',
+      'ocean-family',
+    ];
+    const built = await run(familyArgs);
+    expect(built.code).toBe(0);
+    expect(built.stdout).toContain('[ok] ocean-family.css');
+    expect(nonAscii(built)).toEqual([]);
+
+    fs.rmSync(path.join(dir, 'ocean-family.js'));
+    const stale = await run([...familyArgs, '--check']);
+    expect(stale.code).toBe(1);
+    expect(stale.stderr).toContain('[fail] 1 theme family output(s)');
+    expect(nonAscii(stale)).toEqual([]);
+  });
+
+  it('the suggestion for a quoted glob', async () => {
+    const result = await run(['build', 'themes/*.mjs']);
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('globs are expanded by your shell');
+    expect(nonAscii(result)).toEqual([]);
+  });
+
+  it('a palette candidate preview', async () => {
+    fs.writeFileSync(
+      path.join(dir, 'palette.config.json'),
+      JSON.stringify({
+        modeStrategy: 'dark-only',
+        stops: [10, 50, 90],
+        families: [{id: 'blue', seed: '#0074e2'}],
+      }),
+    );
+    const result = await run(['palette', 'generate', 'palette.config.json']);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('1 families, 3 stops, dark');
+    expect(nonAscii(result)).toEqual([]);
+  });
+});

package/clients/cli/commands/build-theme.flag-docs.test.mjs

@@ -0,0 +1,110 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every `theme build` flag interaction is discoverable.
+ *
+ * Each combination the command refuses is refused before any work, and the
+ * refusal is named in the machine-readable manifest's description of at least
+ * one of the flags involved. Flags that fill in a value when omitted state
+ * their default there too.
+ */
+
+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 {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+
+/** @type {string} */
+let dir;
+/** @type {Map<string, string>} flag token -> manifest description */
+let descriptions;
+
+beforeAll(async () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-flag-docs-'));
+  // Refusals happen before a theme loads; the files only need to exist.
+  for (const name of ['a.mjs', 'b.mjs']) {
+    fs.writeFileSync(path.join(dir, name), 'export default {};\n');
+  }
+
+  const manifest = JSON.parse(
+    (await runCli(['--json', 'manifest'], dir)).stdout,
+  ).data;
+  const theme = manifest.commands.find(command => command.name === 'theme');
+  const build = theme.subcommands.find(
+    command => command.name === 'theme build',
+  );
+  descriptions = new Map(
+    build.options.map(option => [
+      /** @type {string} */ (option.flag.match(/--[a-z-]+/)?.[0]),
+      option.description,
+    ]),
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** @param {string} flag */
+function description(flag) {
+  const text = descriptions.get(flag);
+  expect(text, `manifest has no ${flag} option`).toBeDefined();
+  return /** @type {string} */ (text);
+}
+
+/**
+ * Whether `a`'s description names `b`, or `b`'s names `a`. `b` may also be a
+ * pattern for a condition that is not a flag.
+ * @param {string} a
+ * @param {string | RegExp} b
+ */
+function documented(a, b) {
+  const partner = typeof b === 'string' ? new RegExp(`${b}\\b`) : b;
+  if (partner.test(description(a))) return true;
+  return (
+    typeof b === 'string' &&
+    descriptions.has(b) &&
+    new RegExp(`${a}\\b`).test(description(b))
+  );
+}
+
+const REFUSED = [
+  {
+    pair: ['--family', '--out'],
+    args: ['--family', 'a.mjs', 'b.mjs', '--family-key', 'k', '--out', 'x.css'],
+  },
+  {
+    pair: ['--family', '--watch'],
+    args: ['--family', 'a.mjs', 'b.mjs', '--family-key', 'k', '--watch'],
+  },
+  {pair: ['--family', '--family-key'], args: ['--family', 'a.mjs', 'b.mjs']},
+  {pair: ['--family-key', '--family'], args: ['a.mjs', '--family-key', 'k']},
+  {pair: ['--check', '--watch'], args: ['a.mjs', '--check', '--watch']},
+  {
+    pair: ['--out', /several|more than one|single theme|one theme/i],
+    args: ['a.mjs', 'b.mjs', '--out', 'x.css'],
+  },
+  {pair: ['--watch', '--json'], args: ['a.mjs', '--watch']},
+];
+
+describe('theme build flag interactions are documented', () => {
+  for (const {pair, args} of REFUSED) {
+    const [a, b] = pair;
+    it(`${a} with ${String(b)} is refused and documented`, async () => {
+      const result = await runCli(['--json', 'theme', 'build', ...args], dir);
+
+      expect(result.code).toBe(1);
+      expect(JSON.parse(result.stdout).code).toBe(
+        ERROR_CODES.ERR_THEME_INVALID,
+      );
+      expect(documented(a, b)).toBe(true);
+    });
+  }
+
+  it('flags that fill in an omitted value state their default', () => {
+    expect(description('--out')).toMatch(/default/i);
+    expect(description('--icons-specifier')).toMatch(/default/i);
+  });
+});

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

@@ -33,7 +33,7 @@ import {fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, text, list, code} from '../formatters/index.mjs';
+import {emit, section, text, list, records, code} from '../formatters/index.mjs';
 import {logger} from '../../../api/logger.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -196,7 +196,7 @@ async function warnOnThemeIntegrationIssues(json) {
   try {
     const project = await Project.load(process.cwd());
     await project.themes();
-    await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+    await warnOnIntegrationIssues(project, {json});
   } catch {
     // Never let the nudge break the command.
   }
@@ -229,47 +229,6 @@ function printThemeList(themes) {
   );
 }
 
-/**
- * Render the targets as one greppable line each, under an aligned header. A
- * `records()` block would be five lines per target — over a thousand for the
- * full surface, which is the view this command exists to make readable.
- * @param {import('../../../api/theme/theme.type.mjs').ThemeTargetEntry[]} targets
- * @returns {string}
- */
-function formatTargetsTable(targets) {
-  const rows = targets.map(t => ({
-    key: t.deprecatedFor
-      ? `${t.key} [deprecated; use ${t.deprecatedFor}]`
-      : t.key,
-    component: t.component,
-    props: t.props.join(', ') || '-',
-    states: t.states.join(', ') || '-',
-  }));
-  const head = {
-    key: 'key',
-    component: 'component',
-    props: 'props',
-    states: 'states',
-  };
-  const width = (/** @type {'key'|'component'|'props'} */ field) =>
-    [head, ...rows].reduce((max, r) => Math.max(max, r[field].length), 0);
-  const w = {
-    key: width('key'),
-    component: width('component'),
-    props: width('props'),
-  };
-  const line = (/** @type {typeof head} */ r) =>
-    [
-      r.key.padEnd(w.key),
-      r.component.padEnd(w.component),
-      r.props.padEnd(w.props),
-      r.states,
-    ]
-      .join('  ')
-      .trimEnd();
-  return [line(head), ...rows.map(line)].join('\n');
-}
-
 /**
  * @param {import('commander').Command} program
  */
@@ -369,7 +328,7 @@ export function registerTheme(program) {
         emit(
           section(
             'Palette candidate',
-            `${result.data.familyCount} families · ${result.data.stopCount} stops · ${result.data.modes.join(', ')}`,
+            `${result.data.familyCount} families, ${result.data.stopCount} stops, ${result.data.modes.join(', ')}`,
           ),
           code(serializePaletteCandidate(result.data.candidate).trimEnd()),
         );
@@ -426,7 +385,7 @@ export function registerTheme(program) {
                 {
                   name: `astryx theme build ${entry.file.replace(/['"]/g, '')}`,
                   reason:
-                    'globs are expanded by your shell — pass the pattern unquoted, or list the files',
+                    'globs are expanded by your shell; pass the pattern unquoted, or list the files',
                 },
               ]
             : undefined,
@@ -491,7 +450,7 @@ export function registerTheme(program) {
       // Non-watch: delegate to the API compiler, once per theme, in argument
       // order. Enable human output unless in --json mode (log → stdout via
       // humanLog, warn/error → stderr). The "Building theme from" line, the
-      // ✓/warning lines, and the install instructions are all emitted from
+      // [ok]/[warn] lines, and the install instructions are all emitted from
       // inside themeBuild via the shared logger.
       logger.setSilent(json);
 
@@ -574,8 +533,8 @@ export function registerTheme(program) {
         emit(
           text(
             options.check
-              ? `\n${stale ? '✗' : '✓'} Checked ${entries.length} themes.`
-              : `\n✓ Built ${entries.length} themes.`,
+              ? `\n${stale ? '[fail]' : '[ok]'} Checked ${entries.length} themes.`
+              : `\n[ok] Built ${entries.length} themes.`,
           ),
         );
       }
@@ -811,9 +770,16 @@ export function registerTheme(program) {
       emit(
         section(
           'Theming targets',
-          `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}`,
+          `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}\n(key - component - props - states - className - deprecatedFor)`,
         ),
-        text(formatTargetsTable(targets)),
+        records(targets, {
+          fields: ['key', 'component', 'props', 'states', 'className', 'deprecatedFor'],
+          layout: 'inline',
+          format: {
+            deprecatedFor: (/** @type {string|null} */ v) =>
+              v ? `deprecated; use ${v}` : '',
+          },
+        }),
         text(
           [
             `Each key goes under \`components\` in defineTheme; it paints \`.astryx-<key>\`.`,

package/clients/cli/commands/build-theme.path-safety.test.mjs

@@ -7,15 +7,21 @@
  *   - Theme name with `..` segments cannot escape the output directory.
  *   - Theme name with `/` is rejected with a clear error (vs. ENOENT).
  *   - Multi-file write is atomic: if one file fails, none are left behind.
+ *   - An `--out` escape, or an output directory that cannot be created, fails
+ *     with a registered error code.
  *
  * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {themeBuild} from '../../../api/theme/build/build.mjs';
+import {AstryxError} from '../../../api/error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 
 function writeTheme(dir, name) {
   fs.mkdirSync(dir, {recursive: true});
@@ -93,3 +99,82 @@ describe('theme build path safety', () => {
     expect(entries).toEqual(['theme.mjs']);
   });
 });
+
+describe('theme build output-path failures carry registered codes', () => {
+  // These reach the output-path step, which runs after CSS generation.
+  beforeAll(() => {
+    ensureCoreBuilt();
+  }, 200_000);
+
+  const registered = new Set(Object.values(ERROR_CODES));
+
+  /** @param {string[]} args @param {string} cwd */
+  async function buildJson(args, cwd) {
+    const result = await runCli(['--json', 'theme', 'build', ...args], cwd);
+    return {result, envelope: JSON.parse(result.stdout)};
+  }
+
+  it('reports an --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+
+    const {result, envelope} = await buildJson(
+      [path.relative(project, themeFile), '--out', '../escaped.css'],
+      project,
+    );
+
+    expect(result.code).toBe(1);
+    expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    expect(registered.has(envelope.code)).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+  });
+
+  it('reports an --out path that escapes through a symlink as ERR_PATH_TRAVERSAL', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    fs.symlinkSync(outside, path.join(project, 'link'), 'dir');
+
+    const {result, envelope} = await buildJson(
+      [path.relative(project, themeFile), '--out', 'link/escaped.css'],
+      project,
+    );
+
+    expect(result.code).toBe(1);
+    expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('reports an output directory that cannot be created as ERR_WRITE_FAILED', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    // A regular file where the output directory would have to be created.
+    fs.writeFileSync(path.join(project, 'blocker'), '');
+
+    const {result, envelope} = await buildJson(
+      [path.relative(project, themeFile), '--out', 'blocker/ocean.css'],
+      project,
+    );
+
+    expect(result.code).toBe(1);
+    expect(envelope.code).toBe(ERROR_CODES.ERR_WRITE_FAILED);
+    expect(registered.has(envelope.code)).toBe(true);
+  });
+
+  it('themeBuild() rejects an escaping out path with an AstryxError', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+
+    const build = themeBuild(
+      path.relative(project, themeFile),
+      {out: '../escaped.css'},
+      {cwd: project},
+    );
+
+    await expect(build).rejects.toBeInstanceOf(AstryxError);
+    await expect(build).rejects.toMatchObject({
+      code: ERROR_CODES.ERR_PATH_TRAVERSAL,
+    });
+  });
+});

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);
+});