@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.dea6813

package/assets/templates/pages/table-tree/template.doc.mjs

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'page',
+  name: 'Tree Table',
+  displayName: 'Tree Table',
+  description:
+    'Hierarchical table where every parent row rolls up from its children — a code repository whose folders show the newest commit beneath them, beside a detail sidebar and a rendered README. Columns resize, siblings sort within their own level, arrow keys walk the rows, and search prunes the tree to matching branches. Tree, hierarchy, nested rows, drilldown, expand, collapse, resizable, expandable, file browser, repository, rolled-up parents.',
+  isReady: true,
+  category: 'Table - Tree/Hierarchical List',
+};

package/authoring/config/config.doc.mjs

@@ -48,7 +48,7 @@ export const doc = {
       name: 'debug',
       type: '(event: DebugEvent) => void',
       description:
-        'Record every command run. The handler is synchronous; promises are not awaited and output goes to stderr. Declare `debug` directly in this file so early commands can discover it. An integration can supply one too, as a `debug` named export from its manifest — both run; set `{"astryx": {"inheritDebug": false}}` in package.json to take only your own.',
+        'Record every command run. The handler is synchronous; promises are not awaited and output goes to stderr. Declare `debug` directly in this file so early commands can discover it. An integration can supply one too, as a `debug` named export from its manifest. Every handler runs: yours first, then each integration\'s in load order (the `integrations` list, then autolinked ones). A handler that throws is skipped; the others still run and the command\'s result does not change. Set `{"astryx": {"inheritDebug": false}}` in package.json to take only your own.',
       example:
         "event => appendFileSync('runs.ndjson', JSON.stringify(event) + '\\n')",
     },

package/authoring/config/debug-composition.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `debug` accepts handlers from integrations, so both public entries for
+ * it — the exported `AstryxConfig` type and `astryx docs authoring config` —
+ * must state how those handlers combine with the app's own: the contribution
+ * form, the order, what a failing handler does, and the refusal control.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import ts from 'typescript';
+import {describe, expect, it} from 'vitest';
+import {doc} from './config.doc.mjs';
+
+const TYPE_FILE = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'type.ts',
+);
+const source = ts.createSourceFile(
+  TYPE_FILE,
+  fs.readFileSync(TYPE_FILE, 'utf8'),
+  ts.ScriptTarget.Latest,
+  true,
+);
+
+/** @param {ts.Node} node @returns {string} */
+function jsdocText(node) {
+  return ts
+    .getJSDocCommentsAndTags(node)
+    .map(jsdoc => ts.getTextOfJSDocComment(jsdoc.comment) ?? '')
+    .join('\n');
+}
+
+/** @param {(node: ts.Node) => boolean} match @returns {ts.Node} */
+function findTopLevel(match) {
+  const node = source.statements.find(match);
+  if (!node) throw new Error('declaration not found in config/type.ts');
+  return node;
+}
+
+const configInterface = /** @type {ts.InterfaceDeclaration} */ (
+  findTopLevel(
+    node => ts.isInterfaceDeclaration(node) && node.name.text === 'AstryxConfig',
+  )
+);
+const debugMember = configInterface.members.find(
+  member =>
+    ts.isPropertySignature(member) && member.name.getText(source) === 'debug',
+);
+if (!debugMember) throw new Error('AstryxConfig has no debug member');
+
+const debugConfigAlias = findTopLevel(
+  node => ts.isTypeAliasDeclaration(node) && node.name.text === 'DebugConfig',
+);
+
+const schemaField = doc.fields.find(field => field.name === 'debug');
+
+const ENTRIES = {
+  'the AstryxConfig type': jsdocText(debugMember),
+  'astryx docs authoring config': schemaField?.description ?? '',
+};
+
+describe.each(Object.entries(ENTRIES))('debug entry in %s', (_, text) => {
+  it('says integrations contribute, and in what form', () => {
+    expect(text).toMatch(/integration/i);
+    expect(text).toMatch(/`debug` named export/);
+  });
+
+  it('says every handler runs, the app first, then integrations in load order', () => {
+    expect(text).toMatch(/\bfirst\b/i);
+    expect(text).toMatch(/load order/i);
+  });
+
+  it('says a handler that throws is skipped without affecting the others', () => {
+    expect(text).toMatch(/throws is skipped/i);
+    expect(text).toMatch(/others still run/i);
+  });
+
+  it('names the one control that refuses inherited handlers', () => {
+    expect(text).toContain('{"astryx": {"inheritDebug": false}}');
+  });
+});
+
+describe('DebugConfig', () => {
+  it('does not claim that leaving debug out records nothing', () => {
+    const text = jsdocText(debugConfigAlias);
+    expect(text).not.toMatch(/nothing is recorded/i);
+    expect(text).toMatch(/integration/i);
+  });
+});

package/authoring/config/type.ts

@@ -56,8 +56,9 @@ export interface XleComponent {
 /**
  * Record every astryx command run in this project.
  *
- * A function that receives each run. Setting it is the whole opt-in; leave it
- * out and nothing is recorded.
+ * A function that receives each run. Leaving it out does not stop a handler an
+ * integration contributes; see {@link AstryxConfig.debug} for how the two
+ * combine and how to refuse inherited handlers.
  *
  * ```
  * export default {
@@ -80,7 +81,18 @@ export interface AstryxConfig {
   hooks?: {
     postCodemod?: PostCodemodHook[];
   };
-  /** Record every astryx command run in this project. See {@link DebugConfig}. */
+  /**
+   * Record every astryx command run in this project. See {@link DebugConfig}.
+   *
+   * An integration can contribute a handler too, as a `debug` named export
+   * from its `astryx.integration.*` module. Every handler receives the run:
+   * this one first, then each integration's in load order (the ones
+   * `integrations` lists, in that order, then autolinked ones). A handler that
+   * throws is skipped; the others still run and the command's result does not
+   * change. To refuse inherited handlers, set
+   * `{"astryx": {"inheritDebug": false}}` in the project's package.json; this
+   * handler still runs.
+   */
   debug?: DebugConfig;
   /** Route gap reports through a project-owned handler. See {@link GapReportHandler}. */
   gapReport?: GapReportHandler;

package/clients/cli/command-load-failure.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A command whose module fails to import still answers: with --json, one
+ * error envelope on stdout; without it, the error on stderr. Exit 1 either way.
+ *
+ * The failure is injected with a module-load hook in a real subprocess, so the
+ * lazy command registry in index.mjs sees what a broken install would give it.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const BIN = fileURLToPath(new URL('./bin/astryx.mjs', import.meta.url));
+
+/** @type {string} */
+let dir;
+/** @type {string} */
+let register;
+
+beforeAll(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-load-failure-'));
+  const hooks = path.join(dir, 'hooks.mjs');
+  fs.writeFileSync(
+    hooks,
+    [
+      'export async function load(url, context, nextLoad) {',
+      "  if (url.endsWith('/clients/cli/commands/blog.mjs')) {",
+      "    throw new Error('simulated load failure');",
+      '  }',
+      '  return nextLoad(url, context);',
+      '}',
+      '',
+    ].join('\n'),
+  );
+  register = path.join(dir, 'register.mjs');
+  fs.writeFileSync(
+    register,
+    `import {register} from 'node:module';\nregister(${JSON.stringify(pathToFileURL(hooks).href)});\n`,
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** @param {string[]} args */
+function run(args) {
+  const res = spawnSync(
+    process.execPath,
+    ['--import', pathToFileURL(register).href, BIN, ...args],
+    {cwd: dir, encoding: 'utf-8', timeout: 20_000},
+  );
+  return {status: res.status, stdout: res.stdout, stderr: res.stderr};
+}
+
+describe('a command that fails to load', () => {
+  it('answers --json with one error envelope, exit 1', () => {
+    const {status, stdout, stderr} = run(['blog', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toMatchObject({apiVersion: 1, code: 'ERR_UNKNOWN'});
+    expect(envelope.error).toMatch(/blog.*simulated load failure/);
+  });
+
+  it('reports the failure on stderr without --json, exit 1', () => {
+    const {status, stdout, stderr} = run(['blog']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/blog.*failed to load.*simulated load failure/s);
+  });
+
+  it('leaves the other commands working', () => {
+    const {status, stdout} = run(['docs', '--json']);
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).type).toMatch(/^docs\./);
+  });
+});

package/clients/cli/commands/blog.mjs

@@ -24,6 +24,18 @@ import {resultSet} from '../../../foundation/debug/index.mjs';
 import {doc as blogCommand} from './blog.doc.mjs';
 import {doc as blogFn} from '../../../api/blog/blog.doc.mjs';
 
+/** Every field of a post in the JSON, in order; record() skips empty ones. */
+const POST_FIELDS = [
+  'slug',
+  'title',
+  'description',
+  'date',
+  'type',
+  'authors',
+  'link',
+  'textUrl',
+];
+
 /**
  * @param {import('commander').Command} program
  */
@@ -62,22 +74,25 @@ export function registerBlog(program) {
         const {feedUrl, posts} = result.data;
         if (posts.length === 0) {
           emit(
-            section('Astryx blog', `feed: ${feedUrl}`),
+            section('Astryx blog'),
+            record({feedUrl}),
             text('No posts found in the feed.'),
           );
           return answered;
         }
-        // One record per post — fields mirror the JSON post shape; empty
-        // fields (type/textUrl) are skipped by record().
         emit(
-          section('Astryx blog', `feed: ${feedUrl}`),
-          records(posts, {fields: ['slug', 'title', 'type', 'textUrl']}),
+          section('Astryx blog'),
+          record({feedUrl}),
+          records(posts, {fields: POST_FIELDS}),
           text(`Read one: ${run} astryx blog <slug>`),
         );
       } else {
-        // blog.detail — the feed URL, then the post body emitted verbatim
-        // (code() so article typography/spacing isn't ASCII-normalized).
-        emit(record({feed: result.data.feedUrl}), code(result.data.text));
+        // blog.detail — the post's fields and the feed URL, then the body
+        // verbatim (code() so article typography/spacing isn't ASCII-normalized).
+        emit(
+          record(result.data, {fields: [...POST_FIELDS, 'feedUrl']}),
+          code(result.data.text),
+        );
       }
       return answered;
     },

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

@@ -19,7 +19,10 @@ const FEED = `<?xml version="1.0" encoding="UTF-8"?>
     <item>
       <title>How Astryx works</title>
       <link>${SITE_URL}/blog/how-astryx-works</link>
+      <description>Under the hood &amp; more</description>
       <category>engineering</category>
+      <author>Ada</author>
+      <author>Grace</author>
       <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
       <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
     </item>
@@ -39,6 +42,23 @@ function stubFetch(routes) {
   });
 }
 
+/**
+ * Every non-empty field prints as a `key: value` line under its JSON key.
+ * @param {string} stdout
+ * @param {Record<string, unknown>} fields
+ */
+function expectFields(stdout, fields) {
+  const lines = stdout.split('\n');
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null || value === '' || (Array.isArray(value) && !value.length)) continue;
+    const shown = Array.isArray(value) ? value.join(', ') : String(value);
+    expect(
+      lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown)),
+      `${key}: ${shown}`,
+    ).toBe(true);
+  }
+}
+
 beforeEach(() => {
   vi.stubGlobal(
     'fetch',
@@ -83,10 +103,31 @@ describe('blog CLI — json-enabled', () => {
     const {status, stdout} = await runCli(['blog']);
     expect(status).toBe(0);
     expect(stdout).toMatch(/Astryx blog/);
-    expect(stdout).toMatch(/feed:/);
+    expect(stdout).toMatch(/^feedUrl:/m);
     expect(stdout).toMatch(/how-astryx-works/);
   });
 
+  it('the text list projects every JSON field under its JSON key', async () => {
+    const env = JSON.parse((await runCli(['blog', '--json'])).stdout);
+    const {status, stdout} = await runCli(['blog']);
+    expect(status).toBe(0);
+    expectFields(stdout, {feedUrl: env.data.feedUrl});
+    for (const post of env.data.posts) expectFields(stdout, post);
+    expect(stdout).not.toMatch(/^feed:/m);
+  });
+
+  it('the text detail projects every JSON field, then the post body', async () => {
+    const env = JSON.parse(
+      (await runCli(['blog', 'how-astryx-works', '--json'])).stdout,
+    );
+    const {status, stdout} = await runCli(['blog', 'how-astryx-works']);
+    expect(status).toBe(0);
+    const {text, ...fields} = env.data;
+    expectFields(stdout, fields);
+    expect(stdout).toContain(text);
+    expect(stdout).not.toMatch(/^feed:/m);
+  });
+
   it('surfaces the API error code and exits non-zero for an unknown slug (--json)', async () => {
     const {status, stdout} = await runCli(['blog', 'no-such-post', '--json']);
     expect(status).not.toBe(0);

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

@@ -369,7 +369,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 +426,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 +491,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 +574,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.`,
           ),
         );
       }