Skip to content

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

TypeScript

fix(cli): keep theme command output plain ASCII (#6544)

Joey93b8722e29f4
diff --git a/.changeset/cli-spec-theme-ascii-output.md b/.changeset/cli-spec-theme-ascii-output.md
new file mode 100644
index 0000000000..cf7b167089
--- /dev/null
+++ b/.changeset/cli-spec-theme-ascii-output.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx theme build` and `astryx theme palette generate` now print plain ASCII: status lines use `[ok]`, `[warn]`, `[error]`, `[fail]`, and `[note]` markers instead of symbol glyphs, and theme build messages drop em dashes and ellipses. The reworded font and private-variable messages also appear in the `--json` receipt's `notices` and `warnings`. Generated theme files are unchanged.
+
+@josephfarina
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index 9aa05a0f0a..7e33a1e192 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -1871,7 +1871,7 @@ function validatePrivateVars(themeDef) {
if (prop.startsWith('--_')) {
errors.push(
`Component "${component}" (${[key, ...path].join(' ')}) sets private var "${prop}". ` +
- `Private vars (--_*) are internal — use standard CSS properties ` +
+ `Private vars (--_*) are internal; use standard CSS properties ` +
`(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,
);
}
@@ -2163,14 +2163,14 @@ async function themeBuildInternal(
const noticeMessages = [];
for (const w of warnings) {
warningMessages.push(w);
- logger.warn(` ⚠ ${w}`);
+ logger.warn(` [warn] ${w}`);
}
// Validate no private vars are set directly
const privateVarErrors = validatePrivateVars(themeDef);
for (const e of privateVarErrors) {
warningMessages.push(e);
- logger.error(` ✗ ${e}`);
+ logger.error(` [error] ${e}`);
}
if (privateVarErrors.length > 0) {
logger.error(
@@ -2196,7 +2196,7 @@ async function themeBuildInternal(
// capability exports are checked against what the theme actually asks for.
if (!_defineTheme || !_generateThemeRulesSplit) {
throw new AstryxError(
- 'Could not load @astryxdesign/core/theme — `astryx theme build` requires a ' +
+ 'Could not load @astryxdesign/core/theme: `astryx theme build` requires a ' +
'built, resolvable @astryxdesign/core so it emits the same CSS as the ' +
'runtime <Theme>. Build @astryxdesign/core first (e.g. `pnpm -F @astryxdesign/core ' +
'build`)' +
@@ -2385,10 +2385,10 @@ async function themeBuildInternal(
for (const message of droppedDeclarations) {
const w = `Declaration ${message}. The generated CSS omits it; fix the value in the theme source.`;
warningMessages.push(w);
- logger.warn(` ⚠ ${w}`);
+ logger.warn(` [warn] ${w}`);
}
if (cssParts.length === 0) {
- logger.log('No overrides found — nothing to build.');
+ logger.log('No overrides found; nothing to build.');
return null;
}
// The data-token defaults are theme-independent and go in @layer
@@ -2548,10 +2548,10 @@ async function themeBuildInternal(
const stale = staleBuildOutputs(writes, cwd);
const upToDate = stale.length === 0;
if (upToDate) {
- logger.log(`\n✓ Theme outputs are up to date with ${sourceRelative}.`);
+ logger.log(`\n[ok] Theme outputs are up to date with ${sourceRelative}.`);
} else {
logger.error(
- `\n✗ ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
+ `\n[fail] ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
);
for (const s of stale) {
logger.error(
@@ -2573,17 +2573,17 @@ async function themeBuildInternal(
writeBuildOutputs(writes);
- logger.log(`\n✓ ${path.relative(cwd, outPath)}`);
+ logger.log(`\n[ok] ${path.relative(cwd, outPath)}`);
logger.log(
` ${tokenCount} token overrides, ${componentCount} component overrides`,
);
logger.log(` ${size} KB`);
- logger.log(`✓ ${path.relative(cwd, jsPath)}`);
- logger.log(`✓ ${path.relative(cwd, dtsPath)}`);
+ logger.log(`[ok] ${path.relative(cwd, jsPath)}`);
+ logger.log(`[ok] ${path.relative(cwd, dtsPath)}`);
if (variantDtsPath && variantDecl) {
const augCount = (variantDecl.match(/': true;/g) || []).length;
logger.log(
- `✓ ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
+ `[ok] ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
);
}
@@ -2593,7 +2593,7 @@ async function themeBuildInternal(
const cssImport = importSpecifier(relOutDir, cssBase) + '.css';
const exportName = `${toIdentifier(baseName)}Theme`;
logger.log(`
-Install in your app (paths are relative to a file in src/ — adjust if yours lives elsewhere):
+Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
import { ${exportName} } from '${jsImport}';
import '${cssImport}';
@@ -2625,7 +2625,7 @@ Or with a <link> tag:
// Adaptation rules are resolved theme writes in their own right, so a family
// named only inside one needs the same notice as one named at the root.
for (const family of unloadedFonts) {
- const msg = `Font "${family}" is named by this theme but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`;
+ const msg = `Font "${family}" is named by this theme but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`;
noticeMessages.push(msg);
logger.log(` note: ${msg}`);
}
@@ -2919,11 +2919,11 @@ export async function themeBuildFamily(
const upToDate = stale.length === 0;
if (upToDate) {
logger.log(
- `\n✓ Theme family outputs are up to date with ${sourceRelative}.`,
+ `\n[ok] Theme family outputs are up to date with ${sourceRelative}.`,
);
} else {
logger.error(
- `\n✗ ${stale.length} theme family output(s) are out of date:`,
+ `\n[fail] ${stale.length} theme family output(s) are out of date:`,
);
for (const entry of stale) {
logger.error(
@@ -2943,7 +2943,7 @@ export async function themeBuildFamily(
};
}
writeBuildOutputs(writes);
- for (const output of Object.values(outputs)) logger.log(`✓ ${output}`);
+ for (const output of Object.values(outputs)) logger.log(`[ok] ${output}`);
const themeBindings = members.map(member => bindings.get(member.theme.name));
const relOutDir = path.relative(cwd, outDir) || '.';
const jsImport = importSpecifier(relOutDir, baseName);
@@ -2961,7 +2961,7 @@ Or load the same stylesheet natively:
];
const notices = unloadedFonts.map(
family =>
- `Font "${family}" is named by this theme family but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`,
+ `Font "${family}" is named by this theme family but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`,
);
for (const notice of notices) logger.log(` note: ${notice}`);
return {
diff --git a/packages/cli/api/theme/build/build.public-component-vars.test.mjs b/packages/cli/api/theme/build/build.public-component-vars.test.mjs
index bfaeff0c5b..0f09d429e8 100644
--- a/packages/cli/api/theme/build/build.public-component-vars.test.mjs
+++ b/packages/cli/api/theme/build/build.public-component-vars.test.mjs
@@ -19,7 +19,7 @@
* next one is covered without touching this file.
*
* Asserted on the receipt's `warnings` rather than on a rejection: a private
- * var is reported (logged `✗`, collected into the receipt) and the build then
+ * var is reported (logged `[error]`, collected into the receipt) and the build then
* emits its CSS and resolves anyway. Asserting a throw would pass for the
* wrong reason — it never throws, which is why a throwaway build read as a
* pass on the first version of #5214.
diff --git a/packages/cli/api/theme/build/font-warning.mjs b/packages/cli/api/theme/build/font-warning.mjs
index 1e3948f2d1..e1828a0894 100644
--- a/packages/cli/api/theme/build/font-warning.mjs
+++ b/packages/cli/api/theme/build/font-warning.mjs
@@ -211,11 +211,11 @@ export function formatFontLoadingHelp(themeName, families) {
const first = families[0];
const slug = first.toLowerCase().replace(/ /g, '-');
return `
-⚠ Theme "${themeName}" names fonts it does not load: ${named}
- The built CSS only sets font-family — load these in your app, or every
+[note] Theme "${themeName}" names fonts it does not load: ${named}
+ The built CSS only sets font-family; load these in your app, or every
browser quietly falls back.
- Google Fonts (add :wght@… axes as your theme's weights require):
+ Google Fonts (add :wght@... axes as your theme's weights require):
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
diff --git a/packages/cli/api/theme/build/font-warning.test.mjs b/packages/cli/api/theme/build/font-warning.test.mjs
index 424004f5a0..ef72ea5644 100644
--- a/packages/cli/api/theme/build/font-warning.test.mjs
+++ b/packages/cli/api/theme/build/font-warning.test.mjs
@@ -227,12 +227,15 @@ describe('formatFontLoadingHelp', () => {
const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);
it('names the theme and every family in the headline', () => {
- expect(help).toContain('⚠');
- expect(help).toContain('ocean');
+ expect(help).toContain('[note] Theme "ocean"');
expect(help).toContain('"Fraunces"');
expect(help).toContain('"JetBrains Mono"');
});
+ it('is plain ASCII', () => {
+ expect(help).not.toMatch(/[\u0080-\uffff]/);
+ });
+
it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
expect(help).toContain(
'<link rel="preconnect" href="https://fonts.googleapis.com"',
diff --git a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
new file mode 100644
index 0000000000..3e31d6662a
--- /dev/null
+++ b/packages/cli/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([]);
+ });
+});
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index 3e31e8e41b..8b1443cc18 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/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.`,
),
);
}