Skip to content

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

TypeScript

feat(cli): render human output through a shared formatter kit (#4686)

Joey700a7af446aa
diff --git a/.changeset/cli-output-formatters.md b/.changeset/cli-output-formatters.md
new file mode 100644
index 0000000000..7f3135e943
--- /dev/null
+++ b/.changeset/cli-output-formatters.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] CLI human (non-`--json`) output now renders through a small, documented formatter kit: consistent, plain-ASCII `key: value` records/sections that mirror `--json` and are greppable by field. Every command was migrated onto it (a lint rule keeps output funneled through the single `emit` sink), and `astryx --help` documents the output contract. `--json` output is unchanged. (#4686)
+@joeyfarina
diff --git a/.github/scripts/cli-smoke-test.mjs b/.github/scripts/cli-smoke-test.mjs
index adea930130..148164b1dc 100644
--- a/.github/scripts/cli-smoke-test.mjs
+++ b/.github/scripts/cli-smoke-test.mjs
@@ -85,43 +85,52 @@ const DETAIL_LEVELS = detailMatch
console.log(`detail levels: ${DETAIL_LEVELS.join(', ')}`);
+// Parse a command's --json envelope. The JSON output is the CLI's source of
+// truth; the human text is a projection, so discovery must not scrape it.
+function runJson(args) {
+ const {stdout} = run(args);
+ try {
+ return JSON.parse(stdout);
+ } catch {
+ return null;
+ }
+}
+
// ---------------------------------------------------------------------------
-// 2. Discover components from astryx component --list
+// 2. Discover components from astryx component --list --json
// ---------------------------------------------------------------------------
console.log('\ncomponent listing');
check('astryx component --list', ['component', '--list']);
-const listResult = run(['component', '--list']);
-const componentNames = listResult.stdout
- .split('\n')
- .filter(line => /^\s+[A-Z]/.test(line))
- .map(line => line.trim().split(/\s{2,}/)[0]);
+// data.components is a map of category/group key -> [{name, package}, ...].
+const listData = runJson(['component', '--list', '--json'])?.data;
+const componentGroups =
+ /** @type {Record<string, Array<{name: string}>>} */ (listData?.components ?? {});
+const componentNames = Object.values(componentGroups)
+ .flat()
+ .map(entry => entry.name);
console.log(`discovered ${componentNames.length} components`);
if (componentNames.length === 0) {
- console.log('\nFATAL: no components discovered from --list output. Aborting.');
+ console.log('\nFATAL: no components discovered from --list --json output. Aborting.');
process.exit(1);
}
// ---------------------------------------------------------------------------
-// 3. Discover categories from the --list output
+// 3. Categories are the group keys of the component map (valid --category args)
// ---------------------------------------------------------------------------
-const categories = listResult.stdout
- .split('\n')
- .filter(line => /^[A-Z].*\(group\)$/.test(line))
- .map(line => line.replace(/\s*\(group\)$/, ''));
+const categories = Object.keys(componentGroups);
console.log(`discovered ${categories.length} categories: ${categories.join(', ')}`);
// ---------------------------------------------------------------------------
-// 4. Discover doc topics from astryx docs
+// 4. Discover doc topics from astryx docs --json
// ---------------------------------------------------------------------------
-const docsResult = run(['docs']);
-const docTopics = docsResult.stdout
- .split('\n')
- .filter(line => /^\s{2}\w+\s{2,}/.test(line))
- .map(line => line.trim().split(/\s{2,}/)[0]);
+const docsData = runJson(['docs', '--json'])?.data;
+const docTopics =
+ /** @type {Array<{topic: string}>} */ (Array.isArray(docsData) ? docsData : [])
+ .map(entry => entry.topic);
console.log(`discovered ${docTopics.length} doc topics: ${docTopics.join(', ')}`);
diff --git a/internal/eslint-plugin-astryx/no-raw-console-cli.js b/internal/eslint-plugin-astryx/no-raw-console-cli.js
index 8e4eb8faf4..7062942a12 100644
--- a/internal/eslint-plugin-astryx/no-raw-console-cli.js
+++ b/internal/eslint-plugin-astryx/no-raw-console-cli.js
@@ -2,25 +2,29 @@
/**
* @file no-raw-console-cli.js
- * @description Ban bare `console.log` in CLI runtime files so it can never
- * corrupt the `--json` stdout contract (#2467).
+ * @description Enforce the CLI's output funnels so `--json` stdout stays clean
+ * and human output stays consistent (#2467).
*
- * The CLI's machine-readable JSON output owns stdout in `--json` mode. A stray
- * `console.log` writes to that same stream and breaks JSON consumers. The
- * sanctioned escape hatch is `humanLog()` (lib/json.mjs), which is a no-op in
- * JSON mode. This rule pushes authors toward it:
+ * Two bans:
*
- * Banned: console.log(...) (writes raw stdout)
- * Allowed: console.error(...) (stderr — never corrupts JSON)
- * console.warn(...) (stderr)
- * humanLog(...) (json-aware stdout)
+ * 1. Bare `console.log` in ANY CLI runtime file. The machine-readable JSON
+ * output owns stdout in `--json` mode; a stray `console.log` corrupts it.
+ * Banned: console.log(...)
+ * Allowed: console.error / console.warn (stderr — never corrupts JSON)
*
- * Autofix rewrites `console.log(` → `humanLog(`. The author is responsible for
- * ensuring `humanLog` is imported from `../lib/json.mjs`; the fix only renames
- * the call so the wrong primitive isn't silently kept.
+ * 2. `humanLog(...)` / `humanWarn(...)` in COMMAND files
+ * (clients/cli/commands/**). Command human output must go through the single
+ * formatter sink `emit(...)` (clients/cli/formatters) so every command renders
+ * consistently; errors/warnings go through `cliError()` (stderr). `humanLog`
+ * is now an internal primitive used only by `emit` and the shared `logger` —
+ * commands should never call it directly.
*
- * A handful of files legitimately write raw stdout — the JSON envelope writers
- * and the banner — and are exempt:
+ * The console.log autofix rewrites `console.log(` → `humanLog(` for non-command
+ * files (the logger/formatters/etc.). There is no autofix for ban #2: moving a
+ * command to `emit` isn't a mechanical rename (emit takes Blocks, not strings).
+ *
+ * Files that legitimately write raw stdout or own the funnels are exempt from
+ * ban #1:
* - packages/cli/foundation/response/json.mjs (defines humanLog / jsonOut)
* - packages/cli/clients/cli/index.mjs (wiring / banner)
* - packages/cli/clients/cli/bin/astryx.mjs (entrypoint / error boundary)
@@ -32,9 +36,18 @@ const EXEMPT_SUFFIXES = [
'packages/cli/clients/cli/bin/astryx.mjs',
];
+// Command files must funnel human output through emit(); humanLog/humanWarn are
+// off-limits there (they remain available to the sink implementers: the logger,
+// the formatters, and cli-error, none of which live under commands/).
+const COMMANDS_DIR = 'clients/cli/commands/';
+
+function normalize(filename) {
+ // Normalize Windows separators so path matching is platform-agnostic.
+ return filename.replace(/\\/g, '/');
+}
+
function isExempt(filename) {
- // Normalize Windows separators so suffix matching is path-agnostic.
- const normalized = filename.replace(/\\/g, '/');
+ const normalized = normalize(filename);
return EXEMPT_SUFFIXES.some(suffix => normalized.endsWith(suffix));
}
@@ -43,7 +56,7 @@ const rule = {
type: 'problem',
docs: {
description:
- 'Ban bare console.log in CLI runtime files; use humanLog so --json stdout stays clean',
+ 'Enforce CLI output funnels: no console.log anywhere; no humanLog/humanWarn in command files (use emit)',
category: 'Astryx Conventions',
recommended: true,
},
@@ -53,6 +66,10 @@ const rule = {
'Do not use console.log in CLI runtime code — it writes raw stdout and ' +
'can corrupt --json output. Use humanLog() (from lib/json.mjs), or ' +
'console.error/console.warn for stderr.',
+ noHumanLogInCommand:
+ 'Do not call {{name}}() in a command file — human stdout must go through ' +
+ 'emit() (clients/cli/formatters), and errors/warnings through cliError(). ' +
+ 'humanLog/humanWarn are internal primitives for the logger and formatters.',
},
schema: [],
},
@@ -61,10 +78,13 @@ const rule = {
if (isExempt(filename)) {
return {};
}
+ const inCommands = normalize(filename).includes(COMMANDS_DIR);
return {
CallExpression(node) {
const callee = node.callee;
+
+ // Ban #1: console.log (all CLI runtime files).
if (
callee.type === 'MemberExpression' &&
!callee.computed &&
@@ -82,6 +102,20 @@ const rule = {
return fixer.replaceText(callee, 'humanLog');
},
});
+ return;
+ }
+
+ // Ban #2: humanLog/humanWarn inside command files.
+ if (
+ inCommands &&
+ callee.type === 'Identifier' &&
+ (callee.name === 'humanLog' || callee.name === 'humanWarn')
+ ) {
+ context.report({
+ node: callee,
+ messageId: 'noHumanLogInCommand',
+ data: {name: callee.name},
+ });
}
},
};
diff --git a/internal/eslint-plugin-astryx/no-raw-console-cli.test.mjs b/internal/eslint-plugin-astryx/no-raw-console-cli.test.mjs
index 6ba4e6be41..1a62d40804 100644
--- a/internal/eslint-plugin-astryx/no-raw-console-cli.test.mjs
+++ b/internal/eslint-plugin-astryx/no-raw-console-cli.test.mjs
@@ -26,10 +26,11 @@ ruleTester.run('no-raw-console-cli', rule, {
code: `console.warn('heads up');`,
filename: '/repo/packages/cli/clients/cli/commands/search.mjs',
},
- // humanLog is the sanctioned json-aware stdout primitive
+ // humanLog is allowed OUTSIDE command files — it's the stdout primitive the
+ // formatter sink (emit) and the shared logger are built on.
{
code: `import {humanLog} from '../../lib/json.mjs'; humanLog('hi');`,
- filename: '/repo/packages/cli/clients/cli/commands/search.mjs',
+ filename: '/repo/packages/cli/clients/cli/formatters/index.mjs',
},
// Exempt: lib/json.mjs defines the raw writers
{
@@ -77,6 +78,18 @@ ruleTester.run('no-raw-console-cli', rule, {
{messageId: 'noRawConsoleLog'},
],
},
+ // Ban #2: humanLog() in a command file must funnel through emit()
+ {
+ code: `humanLog('hi');`,
+ filename: '/repo/packages/cli/clients/cli/commands/search.mjs',
+ errors: [{messageId: 'noHumanLogInCommand'}],
+ },
+ // Ban #2: humanWarn() in a command file — warnings go through cliError()
+ {
+ code: `humanWarn('careful');`,
+ filename: '/repo/packages/cli/clients/cli/commands/build.mjs',
+ errors: [{messageId: 'noHumanLogInCommand'}],
+ },
],
});
diff --git a/packages/cli/clients/cli/commands/blog.mjs b/packages/cli/clients/cli/commands/blog.mjs
index 8c92ba0ebe..062f612e17 100644
--- a/packages/cli/clients/cli/commands/blog.mjs
+++ b/packages/cli/clients/cli/commands/blog.mjs
@@ -15,31 +15,11 @@
*/
import {getRunPrefix} from '../../../foundation/env/package-manager.mjs';
-import {humanLog, jsonOut} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, record, records, code} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {blog as blogApi} from '../../../api/blog/blog.mjs';
-/**
- * @param {import('../../../api/blog/blog.type.mjs').BlogListData} data
- * @param {string} run
- */
-function formatList({feedUrl, posts}, run) {
- const lines = [`\nAstryx blog · feed: ${feedUrl}\n`];
- if (posts.length === 0) {
- lines.push('No posts found in the feed.');
- return lines.join('\n');
- }
- for (const p of posts) {
- lines.push(` ${p.slug}`);
- lines.push(` ${p.title}`);
- if (p.type) lines.push(` ${p.type}`);
- if (p.textUrl) lines.push(` ${p.textUrl}`);
- lines.push('');
- }
- lines.push(`Read one: ${run} astryx blog <slug>`);
- return lines.join('\n');
-}
-
/**
* @param {import('commander').Command} program
*/
@@ -68,11 +48,25 @@ export function registerBlog(program) {
}
if (result.type === 'blog.list') {
- humanLog(formatList(result.data, run));
+ const {feedUrl, posts} = result.data;
+ if (posts.length === 0) {
+ emit(
+ section('Astryx blog', `feed: ${feedUrl}`),
+ text('No posts found in the feed.'),
+ );
+ return;
+ }
+ // 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']}),
+ text(`Read one: ${run} astryx blog <slug>`),
+ );
} else {
- // blog.detail — print the feed URL, then the plaintext body.
- humanLog(`Feed: ${result.data.feedUrl}\n`);
- humanLog(result.data.text);
+ // 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));
}
});
}
diff --git a/packages/cli/clients/cli/commands/blog.test.mjs b/packages/cli/clients/cli/commands/blog.test.mjs
index 569bcc8279..c9fec4fb30 100644
--- a/packages/cli/clients/cli/commands/blog.test.mjs
+++ b/packages/cli/clients/cli/commands/blog.test.mjs
@@ -82,7 +82,8 @@ describe('blog CLI — json-enabled', () => {
it('blog (non-json) still prints the human feed listing', async () => {
const {status, stdout} = await runCli(['blog']);
expect(status).toBe(0);
- expect(stdout).toMatch(/Astryx blog · feed:/);
+ expect(stdout).toMatch(/Astryx blog/);
+ expect(stdout).toMatch(/feed:/);
expect(stdout).toMatch(/how-astryx-works/);
});
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index d5c6d2733f..eec3ac35e0 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.mjs
@@ -20,7 +20,8 @@ import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {spawn} from 'node:child_process';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, 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';
@@ -91,10 +92,10 @@ async function runThemeBuildWatch(file, filePath, options) {
return;
}
building = true;
- humanLog(`\n♻️ Change detected — rebuilding ${rel}...`);
+ emit(text(`\nChange detected — rebuilding ${rel}...`));
await runThemeBuildOnceChild(file, options);
building = false;
- humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);
+ emit(text(`\nWatching ${rel} for changes — press Ctrl-C to stop.`));
if (queued) {
queued = false;
rebuild();
@@ -116,13 +117,13 @@ async function runThemeBuildWatch(file, filePath, options) {
// Announce readiness only AFTER fs.watch is armed — the log is the "safe to
// edit" signal (tests and humans rely on it), so printing it before the watch
// is registered would race: a change in that gap is silently missed.
- humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);
+ emit(text(`\nWatching ${rel} for changes — press Ctrl-C to stop.`));
await new Promise((/** @type {(value?: void) => void} */ resolve) => {
const stop = () => {
clearTimeout(debounce);
watcher.close();
- humanLog('\nStopped watching.');
+ emit(text('\nStopped watching.'));
resolve();
};
process.once('SIGINT', stop);
@@ -130,6 +131,32 @@ async function runThemeBuildWatch(file, filePath, options) {
});
}
+/**
+ * Emit the bundled themes as a bulleted list plus the `theme add` usage hint —
+ * the human projection of a `theme.list` envelope. Shared by `theme list` and
+ * the list affordance of `theme add` (bare `theme add` / `--list`).
+ * @param {import('../../../api/theme/theme.type.mjs').ThemeListEntry[]} themes
+ */
+function printThemeList(themes) {
+ if (themes.length === 0) {
+ emit(text('No themes are bundled with this CLI build.'));
+ return;
+ }
+ const run = getCliInvocation();
+ emit(
+ section('Themes'),
+ list(
+ themes.map(t => {
+ const head = t.maintained ? `${t.slug} (maintained)` : t.slug;
+ return t.description ? [head, t.description] : head;
+ }),
+ ),
+ text(
+ `Usage:\n ${run} theme add <slug> [target-path] Scaffold a theme file you own`,
+ ),
+ );
+}
+
/**
* @param {import('commander').Command} program
*/
@@ -266,21 +293,7 @@ export function registerTheme(program) {
if (json) return jsonOut(result);
- const themes = result.data;
- if (themes.length === 0) {
- humanLog('\nNo themes are bundled with this CLI build.\n');
- return;
- }
- humanLog('\nThemes:\n');
- for (const t of themes) {
- const tag = t.maintained ? ' (maintained)' : '';
- humanLog(` ${t.slug}${tag}`);
- if (t.description) humanLog(` ${t.description}`);
- }
- humanLog('\nUsage:');
- humanLog(
- ` ${getCliInvocation()} theme add <slug> [target-path] Scaffold a theme file you own\n`,
- );
+ printThemeList(result.data);
});
theme
@@ -324,41 +337,30 @@ export function registerTheme(program) {
if (json) return jsonOut(result);
if (result.type === 'theme.list') {
- const themes = result.data;
- humanLog('\nThemes:\n');
- for (const t of themes) {
- const tag = t.maintained ? ' (maintained)' : '';
- humanLog(` ${t.slug}${tag}`);
- if (t.description) humanLog(` ${t.description}`);
- }
- humanLog('\nUsage:');
- humanLog(
- ` ${getCliInvocation()} theme add <slug> [target-path] Scaffold a theme file you own\n`,
- );
+ printThemeList(result.data);
return;
}
// theme.add — print where files landed + how to use the theme.
const {displayName, outputDir, entry, exportName, files} = result.data;
- humanLog(`\n✓ Added ${displayName} theme to ${outputDir}/`);
- for (const f of files) {
- humanLog(` ${outputDir}/${f}`);
- }
const entryModule = importSpecifier(
outputDir,
entry.replace(/\.tsx?$/, ''),
);
- humanLog(`
-Use it in your app (import path is relative to a file in src/ — adjust if yours lives elsewhere):
-
- import { ${exportName} } from '${entryModule}';
-
- <Theme theme={${exportName}}>
- <App />
- </Theme>
-
-This is your copy of the ${displayName} theme — edit ${entry} to make it your own.
-`);
+ emit(
+ text(`[ok] Added ${displayName} theme to ${outputDir}/`),
+ list(files.map(f => `${outputDir}/${f}`)),
+ text(
+ 'Use it in your app (import path is relative to a file in src/ — adjust if yours lives elsewhere):',
+ ),
+ code(
+ `import { ${exportName} } from '${entryModule}';\n\n` +
+ `<Theme theme={${exportName}}>\n <App />\n</Theme>`,
+ ),
+ text(
+ `This is your copy of the ${displayName} theme — edit ${entry} to make it your own.`,
+ ),
+ );
},
);
}
diff --git a/packages/cli/clients/cli/commands/build.mjs b/packages/cli/clients/cli/commands/build.mjs
index 5100c7b792..59aef6ce45 100644
--- a/packages/cli/clients/cli/commands/build.mjs
+++ b/packages/cli/clients/cli/commands/build.mjs
@@ -13,42 +13,53 @@
*/
import {getCliInvocation, formatCliCommand} from '../../../foundation/env/package-manager.mjs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, record, records, ARROW} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {build as buildApi} from '../../../api/build/build.mjs';
/**
- * Print the build playbook (shown when `build` is run with no query).
+ * Emit the build playbook (shown when `build` is run with no query).
* @param {string} run - The CLI invocation prefix (e.g. `npx astryx`).
*/
function printPlaybook(run) {
- const lines = [
- '',
- 'How to build a page with Astryx',
- '',
- "1. Find a starting point for what you're building:",
- ` ${run} build "<what you're building>"`,
- ' → returns the closest [page] template, the [block]s that cover parts,',
- ' and the [component]s to fill the gaps, with a "Compose:" suggestion.',
- '',
- '2. If a [page] template matches → scaffold it and adapt:',
- ` ${run} template <name> [path]`,
- '',
- '3. If nothing matches exactly → 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)`,
- '',
- '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.',
- '',
- `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral`,
- `lookup of any component/doc/template, use \`${run} search <query>\`.`,
- '',
- ];
- for (const l of lines) humanLog(l);
+ 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>\`.`,
+ ),
+ );
}
/**
@@ -98,71 +109,91 @@ export function registerBuild(program) {
result.data;
if (!hasResults) {
- humanLog('');
- humanLog(`No matches for "${q}".`);
- humanLog(`Try a broader term, or browse: ${run} component --list`);
- humanLog('');
+ emit(
+ text(`No matches for "${q}".`),
+ text(`Try a broader term, or browse: ${run} component --list`),
+ );
return;
}
- const printItem = (/** @type {import('../../../api/search/search.type.mjs').SearchResultEntry} */ r, /** @type {string} */ label) => {
- const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
- humanLog('');
- humanLog(` [${label}] ${display}`);
- if (r.description) humanLog(` ${r.description}`);
- humanLog(` → ${formatCliCommand(r.command)}`);
- if (options.verbose) {
- if (r.import) humanLog(` import: ${r.import}`);
- humanLog(` match: ${r.reason} (score ${r.score})`);
- }
- };
-
- humanLog('');
- humanLog(`Building "${q}":`);
-
- // START — the single recommended path.
- humanLog('');
- if (directMatch) {
- humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} template ${pages[0].name} ./src/App.tsx`);
- } else if (pages.length) {
- humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} template ${pages[0].name} --skeleton) and compose the pieces below.`);
- } else {
- humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
- }
+ // 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'];
+ /** @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');
+
+ /** @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(', ')}.`,
+ ),
+ section('RECOMMENDED START', `${startNote}\n${startCmd}`),
+ ];
- // PAGE
if (pages.length) {
- humanLog('');
- humanLog(directMatch ? 'PAGE TEMPLATE — direct match:' : 'CLOSEST PAGE TEMPLATES — layout reference:');
- pages.forEach(p => printItem(p, directMatch ? 'page' : 'closest'));
+ out.push(
+ section(
+ 'PAGE TEMPLATES',
+ directMatch
+ ? 'Closest full-page templates — scaffold one, then adapt it.'
+ : 'Closest full-page templates — use as a layout reference.',
+ ),
+ records(pages, recordOpts),
+ );
}
-
- // FRAME — always (the page shell).
- humanLog('');
- humanLog(`FRAME — page shell (always): ${frame.join(', ')}`);
- humanLog(` full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
-
- // BLOCKS — idea-specific composed patterns.
if (blocks.length) {
- humanLog('');
- humanLog('BLOCKS — drop-in patterns that cover parts of it:');
- blocks.forEach(b => printItem(b, 'block'));
+ out.push(
+ section('BLOCKS', 'Drop-in patterns that cover parts of the page.'),
+ records(blocks, recordOpts),
+ );
}
-
- // DOMAIN COMPONENTS — idea-specific atoms.
if (domain.length) {
- humanLog('');
- humanLog('DOMAIN COMPONENTS — specific to this idea:');
- domain.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
+ out.push(
+ section('DOMAIN COMPONENTS', 'Components specific to this idea.'),
+ records(domain, recordOpts),
+ );
}
- // FOUNDATION — always (layout/typography/actions).
- humanLog('');
- humanLog(`FOUNDATION — always available (layout/text/actions): ${foundation.join(' ')}`);
-
- // SETUP — so it renders / stays on-system.
- humanLog('');
- humanLog('SETUP — import "@astryxdesign/core/reset.css" + "astryx.css". No <div>/style for layout — use Stack/Grid + tokens.');
- humanLog('');
+ out.push(
+ section('FRAME + FOUNDATION', 'Always-available shell + layout/text/action primitives.'),
+ record({
+ frame,
+ foundation,
+ setup:
+ 'import "@astryxdesign/core/reset.css" + "astryx.css"; no <div>/style for layout — use Stack/Grid + tokens',
+ }),
+ );
+
+ emit(...out);
});
}
diff --git a/packages/cli/clients/cli/commands/component/index.mjs b/packages/cli/clients/cli/commands/component/index.mjs
index a447136bbf..88fefffc35 100644
--- a/packages/cli/clients/cli/commands/component/index.mjs
+++ b/packages/cli/clients/cli/commands/component/index.mjs
@@ -19,7 +19,8 @@ import {
} from '../../lib/component-format.mjs';
import {resolveTheme} from '../../lib/resolve-theme.mjs';
import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';
-import {jsonOut, humanLog} from '../../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, records, code} from '../../formatters/index.mjs';
import {cliError} from '../../lib/cli-error.mjs';
import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
import {component as componentApi} from '../../../../api/component/component.mjs';
@@ -114,47 +115,51 @@ export function registerComponent(program) {
const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));
const themeData = resolveTheme(process.cwd());
+ // Footer shared by the compact + names list views (prose → text()).
+ const listFooter = text(
+ [
+ `Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`,
+ `Usage: ${run} component <name>`,
+ ].join('\n'),
+ );
+
switch (result.type) {
case 'component.list': {
// One list type across all three detail levels; the depth is carried
// in result.data.detail and the grouped map in result.data.components.
if (result.data.detail === 'full') {
- // --detail full — dense per-component docs (signature, props, theming, examples).
- humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));
+ // --detail full — dense per-component docs (signature, props, theming,
+ // examples). Verbatim doc block from the shared formatter.
+ emit(code(await formatBriefAll(coreDir, {zh, lang, themeData})));
break;
}
if (result.data.detail === 'compact') {
- // --detail compact — name + 1-line description per entry.
+ // --detail compact — one record per entry (name + import + 1-line
+ // description), grouped by category. Fields mirror the JSON keys.
const groups = result.data.components;
- humanLog('');
const entries = Object.entries(groups);
+ /** @type {import('../../formatters/index.mjs').Block[]} */
+ const out = [];
for (const [cat, items] of entries) {
// Skip the synthetic group header when there's only one ungrouped category
const isUngrouped =
entries.length === 1 && items.length === 1 && items[0]?.name === cat;
- if (!isUngrouped) humanLog(`${cat} (group)`);
- for (const item of items) {
- const importHint = item.import ? ` ← ${item.import}` : '';
- const desc = item.description ? ` — ${item.description}` : '';
- humanLog(` XDS${item.name}${importHint}${desc}`);
- }
- humanLog('');
+ if (!isUngrouped) out.push(section(cat));
+ out.push(records(items, {fields: ['name', 'import', 'description']}));
}
- humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
- humanLog(`Usage: ${run} component <name>`);
- humanLog('');
+ out.push(listFooter);
+ emit(...out);
break;
}
- // --detail names (default for list views). The API now returns
- // package-qualified entries ({name, package}); the human view omits
- // the core package label for readability but ALWAYS shows the package
- // for integration components (and whenever names collide).
+ // --detail names (default for list views): one record per component
+ // (name + import), sorted A-Z. The import field already conveys
+ // families, so we skip the choppy per-family grouping that interleaved
+ // headerless singletons with "(group)" sections. External or
+ // name-colliding entries stay package-qualified.
const groups = result.data.components;
const CORE_PKG = '@astryxdesign/core';
- // Names that appear under more than one package across the whole
- // listing — these must always be package-qualified to disambiguate.
/** @type {Map<string, Set<string>>} */
const nameCounts = new Map();
for (const items of Object.values(groups)) {
@@ -164,113 +169,92 @@ export function registerComponent(program) {
nameCounts.set(item.name, set);
}
}
- /** @param {string} n */
- const isCollision = n => (nameCounts.get(n)?.size ?? 0) > 1;
/** @param {import('../../../../api/component/component.type.mjs').ComponentListEntry} item */
- const pkgSuffix = item => {
- if (item.package !== CORE_PKG) return ` [${item.package}]`;
- if (isCollision(item.name)) return ` [${item.package}]`;
- return '';
+ const importCell = item => {
+ const importPath = resolveImportPath(coreDir, item.name);
+ const qualify =
+ item.package !== CORE_PKG || (nameCounts.get(item.name)?.size ?? 0) > 1;
+ return qualify ? `${importPath} [${item.package}]` : importPath;
};
- if (options.category) {
- const [cat, comps] = Object.entries(groups)[0];
- humanLog(`\n${cat}:`);
- for (const item of comps) {
- const importPath = resolveImportPath(coreDir, item.name);
- humanLog(` ${item.name} ← ${importPath}${pkgSuffix(item)}`);
- }
- humanLog('');
- } else {
- humanLog('');
- for (const [key, comps] of Object.entries(groups)) {
- const isUngrouped = comps.length === 1 && comps[0]?.name === key;
- if (isUngrouped) {
- const item = comps[0];
- const importPath = resolveImportPath(coreDir, item.name);
- humanLog(`${item.name} ← ${importPath}${pkgSuffix(item)}`);
- } else {
- humanLog(`${key} (group)`);
- for (const item of comps) {
- const importPath = resolveImportPath(coreDir, item.name);
- humanLog(` ${item.name} ← ${importPath}${pkgSuffix(item)}`);
- }
- }
- }
- humanLog('');
- humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
- humanLog(`Usage: ${run} component <name>`);
- humanLog('');
- }
+ const firstGroup = Object.entries(groups)[0];
+ const entries =
+ options.category && firstGroup ? firstGroup[1] : Object.values(groups).flat();
+ const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+
+ emit(
+ options.category && firstGroup
+ ? section(firstGroup[0])
+ : section(`Components (${sorted.length})`),
+ records(
+ sorted.map(item => ({name: item.name, import: importCell(item)})),
+ {fields: ['name', 'import']},
+ ),
+ listFooter,
+ );
break;
}
case 'component.detail': {
- if (detail === 'brief') {
- const resolvedName = (name || '').replace(/^XDS/, '');
- const importHint = resolveImportPath(coreDir, resolvedName);
- humanLog(formatBrief(result.data, resolvedName, importHint, {themeData}));
- } else if (detail === 'compact') {
- const resolvedName = (name || '').replace(/^XDS/, '');
- const importHint = resolveImportPath(coreDir, resolvedName);
- humanLog(formatCompact(result.data, resolvedName, importHint));
- } else {
- const resolvedName = (name || '').replace(/^XDS/, '');
- const importHint = resolveImportPath(coreDir, resolvedName);
- humanLog(formatFull(result.data, {themeData, importHint}));
- }
- const compName = (name || '').replace(/^XDS/, '');
- const related = await findRelatedBlocks(compName);
- if (related.length > 0) {
- humanLog('\nRelated block templates:\n');
- for (const b of related) {
- humanLog(` ${b.dirName}`);
- if (b.description) humanLog(` ${b.description}`);
- }
- humanLog('');
- }
+ const resolvedName = (name || '').replace(/^XDS/, '');
+ const importHint = resolveImportPath(coreDir, resolvedName);
+ const doc =
+ detail === 'brief'
+ ? code(formatBrief(result.data, resolvedName, importHint, {themeData}))
+ : detail === 'compact'
+ ? code(formatCompact(result.data, resolvedName, importHint))
+ : code(formatFull(result.data, {themeData, importHint}));
+ const related = await findRelatedBlocks(resolvedName);
+ emit(
+ doc,
+ related.length > 0 && section('Related block templates'),
+ related.length > 0 && records(related, {fields: ['dirName', 'description']}),
+ );
break;
}
case 'component.detail.props': {
const resolvedName = (name || '').replace(/^XDS/, '');
- humanLog(formatProps({props: result.data}, resolvedName));
+ emit(code(formatProps({props: result.data}, resolvedName)));
break;
}
case 'component.detail.source': {
- humanLog(result.data.source);
+ emit(code(result.data.source));
break;
}
case 'component.detail.showcase': {
- humanLog(result.data.source);
+ emit(code(result.data.source));
break;
}
case 'component.detail.blocks': {
const {showcase, examples, related} = result.data;
+ /** @type {import('../../formatters/index.mjs').Block[]} */
+ const out = [];
if (showcase) {
- humanLog(`\nShowcase: ${showcase.displayName}`);
- if (showcase.description) humanLog(` ${showcase.description}`);
+ out.push(
+ section('Showcase'),
+ record(showcase, {fields: ['displayName', 'description']}),
+ );
}
if (examples.length > 0) {
- humanLog('\nExamples:\n');
- for (const b of examples) {
- humanLog(` ${b.name}`);
- if (b.description) humanLog(` ${b.description}`);
- }
+ out.push(
+ section('Examples'),
+ records(examples, {fields: ['name', 'description']}),
+ );
}
if (related.length > 0) {
- humanLog(`\nRelated: ${related.length} blocks that use ${result.data.component}\n`);
- for (const b of related) {
- humanLog(` ${b.name}`);
- }
+ out.push(
+ section(`Related: ${related.length} blocks that use ${result.data.component}`),
+ list(related.map(b => b.name)),
+ );
}
if (!showcase && examples.length === 0 && related.length === 0) {
- humanLog(`\nNo blocks found for ${result.data.component}`);
+ out.push(text(`No blocks found for ${result.data.component}`));
}
- humanLog('');
+ emit(...out);
break;
}
}
diff --git a/packages/cli/clients/cli/commands/detail-levels.test.mjs b/packages/cli/clients/cli/commands/detail-levels.test.mjs
index b95261182c..ec6c969755 100644
--- a/packages/cli/clients/cli/commands/detail-levels.test.mjs
+++ b/packages/cli/clients/cli/commands/detail-levels.test.mjs
@@ -58,8 +58,10 @@ describe('--detail level ordering: component --list', () => {
expect(brief).not.toMatch(/ \u2014 /);
});
- it('compact has 1-line descriptions (name + em-dash separator)', () => {
- expect(compact).toMatch(/ \u2014 /);
+ it('compact has descriptions (records expose a description field)', () => {
+ // Migrated to the shared formatter kit: compact renders one record per entry
+ // (name/import/description) rather than a single em-dash-joined line.
+ expect(compact).toMatch(/^description:/m);
});
it('full has dense per-entry docs (props, targets, and import hints)', () => {
@@ -114,8 +116,8 @@ describe('--detail level ordering: hook --list', () => {
expect(brief).not.toMatch(/ \u2014 /);
});
- it('compact has 1-line descriptions (name + em-dash separator)', () => {
- expect(compact).toMatch(/ \u2014 /);
+ it('compact has per-hook descriptions (records with a description field)', () => {
+ expect(compact).toMatch(/description:/);
});
it('full has dense docs (param tables and import statements)', () => {
diff --git a/packages/cli/clients/cli/commands/discover.mjs b/packages/cli/clients/cli/commands/discover.mjs
index 3f14113bcd..159aa66183 100644
--- a/packages/cli/clients/cli/commands/discover.mjs
+++ b/packages/cli/clients/cli/commands/discover.mjs
@@ -11,11 +11,15 @@
*/
import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mjs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, record, records, list, code} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {discover as discoverApi} from '../../../api/discover/discover.mjs';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+// Max components to list inline per package before summarizing with "+N more".
+const MAX_COMPONENTS_SHOWN = 10;
+
/**
* @param {import('commander').Command} program
*/
@@ -55,87 +59,77 @@ export function registerDiscover(program) {
switch (result.type) {
case 'discover.list': {
if (result.data.length === 0) {
- humanLog('');
if (result.meta && result.meta.configured === false) {
- humanLog('No integrations configured.');
- humanLog('');
- humanLog('Add integration package names to astryx.config.mjs:');
- humanLog('');
- humanLog(' export default {');
- humanLog(" integrations: ['@scope/your-integration'],");
- humanLog(' };');
+ emit(
+ text('No integrations configured.'),
+ text('Add integration package names to astryx.config.mjs:'),
+ code(
+ "export default {\n integrations: ['@scope/your-integration'],\n};",
+ ),
+ );
} else {
- humanLog('No external components found in configured integrations.');
+ emit(text('No external components found in configured integrations.'));
}
- humanLog('');
- } else {
- humanLog('');
- for (const pkg of result.data) {
- const count = pkg.components.length;
- const label = count === 1 ? 'component' : 'components';
- const heading = pkg.displayName
- ? pkg.displayName + ' ' + pkg.name + ' (' + count + ' ' + label + ')'
- : pkg.name + ' (' + count + ' ' + label + ')';
- humanLog(heading);
- if (pkg.description) humanLog(' ' + pkg.description);
+ break;
+ }
- if (options.components) {
- for (const comp of pkg.components) humanLog(' ' + comp);
- } else {
- const maxShow = 10;
- const shown = pkg.components.slice(0, maxShow);
- const remaining = count - maxShow;
- const list = shown.join(', ');
- humanLog(remaining > 0 ? ' ' + list + ', +' + remaining + ' more' : ' ' + list);
- }
- humanLog('');
- }
- humanLog('Usage:');
- humanLog(` ${run} discover <package> Browse a package`);
- humanLog(` ${run} discover <package>/Component View component docs`);
- humanLog(` ${run} discover <search> Search all packages`);
- humanLog('');
+ // One record per package — fields mirror the JSON entry. The default
+ // view summarizes each package's components (first N + "+N more");
+ // --components lists them all (record comma-joins the full array).
+ /** @type {import('../formatters/index.mjs').RecordOptions} */
+ const listOpts = {fields: ['displayName', 'name', 'description', 'components']};
+ if (!options.components) {
+ listOpts.format = {
+ components: (/** @type {string[]} */ comps) => {
+ const shown = comps.slice(0, MAX_COMPONENTS_SHOWN);
+ const remaining = comps.length - MAX_COMPONENTS_SHOWN;
+ return remaining > 0
+ ? `${shown.join(', ')}, +${remaining} more`
+ : shown.join(', ');
+ },
+ };
}
+ emit(
+ records(result.data, listOpts),
+ text(
+ [
+ 'Usage:',
+ ` ${run} discover <package> Browse a package`,
+ ` ${run} discover <package>/Component View component docs`,
+ ` ${run} discover <search> Search all packages`,
+ ].join('\n'),
+ ),
+ );
break;
}
case 'discover.detail': {
- humanLog('');
const d = result.data;
- const detailHeading = d.displayName
- ? d.displayName + ' ' + d.name + ' (' + d.components.length + ' components)'
- : d.name + ' (' + d.components.length + ' components)';
- humanLog(detailHeading);
- if (d.description) humanLog(' ' + d.description);
- humanLog('');
- for (const comp of result.data.components) humanLog(' ' + comp);
- humanLog('');
- humanLog(`Usage: ${run} discover ` + result.data.name + '/<ComponentName>');
- humanLog('');
+ emit(
+ record(d, {fields: ['displayName', 'name', 'description', 'components']}),
+ text(`Usage: ${run} discover ${d.name}/<ComponentName>`),
+ );
break;
}
case 'discover.detail.doc': {
const docs = result.data;
- if (detail === 'brief') {
- humanLog(formatBrief(docs, docs.name, ''));
- } else if (detail === 'compact') {
- humanLog(formatCompact(docs, docs.name, ''));
- } else {
- humanLog(formatFull(docs));
- }
- humanLog('');
+ const md =
+ detail === 'brief'
+ ? formatBrief(docs, docs.name, '')
+ : detail === 'compact'
+ ? formatCompact(docs, docs.name, '')
+ : formatFull(docs);
+ emit(code(md));
break;
}
case 'discover.search': {
- humanLog('');
- humanLog('Found ' + result.data.matches.length + ' matches for "' + result.data.query + '":');
- humanLog('');
- for (const m of result.data.matches) {
- humanLog(` ${run} discover ` + m.package + '/' + m.component);
- }
- humanLog('');
+ const {query: q, matches} = result.data;
+ emit(
+ section(`Found ${matches.length} matches for "${q}"`),
+ list(matches.map(m => `${run} discover ${m.package}/${m.component}`)),
+ );
break;
}
}
diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjs
index 2b29688e08..fc641b0f5b 100644
--- a/packages/cli/clients/cli/commands/docs.mjs
+++ b/packages/cli/clients/cli/commands/docs.mjs
@@ -13,7 +13,8 @@
*/
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, records, text, code} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {docs as docsApi} from '../../../api/docs/docs.mjs';
@@ -76,8 +77,8 @@ function formatBlock(block, detail) {
case 'list': {
const prefix = block.style === 'ordered' ? (/** @type {number} */ i) => `${i + 1}. `
- : block.style === 'dont' ? () => '❌ '
- : block.style === 'do' ? () => '✓ '
+ : block.style === 'dont' ? () => 'x '
+ : block.style === 'do' ? () => '+ '
: () => '- ';
return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
}
@@ -135,7 +136,7 @@ export function registerDocs(program) {
program
.command('docs [topic] [section]')
.description('Print reference docs')
- .action(async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ section) => {
+ .action(async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ sectionName) => {
const run = getCliInvocation();
const lang = program.opts().lang || null;
const zh = program.opts().zh || false;
@@ -145,7 +146,7 @@ export function registerDocs(program) {
let result;
try {
- result = await docsApi(topic, section, {lang, zh, dense});
+ result = await docsApi(topic, sectionName, {lang, zh, dense});
} catch (e) {
// docs API throws structured errors with {name, reason} suggestions —
// pass them through untouched so the CLI envelope matches the API.
@@ -158,22 +159,28 @@ export function registerDocs(program) {
switch (result.type) {
case 'docs.list': {
- humanLog('\nAvailable docs:\n');
- for (const entry of result.data) {
- humanLog(` ${entry.topic.padEnd(14)} ${entry.description}`);
- }
- humanLog(`\nUsage: ${run} docs <topic>`);
- humanLog(` ${run} docs <topic> <section>\n`);
+ // The text view mirrors the JSON list: one record per topic (topic +
+ // description), then the usage footer as plain prose.
+ emit(
+ section('Available docs'),
+ records(result.data, {fields: ['topic', 'description']}),
+ text(
+ [
+ `Usage: ${run} docs <topic>`,
+ ` ${run} docs <topic> <section>`,
+ ].join('\n'),
+ ),
+ );
break;
}
case 'docs.detail': {
- humanLog(formatReferenceFull(result.data, detail));
+ emit(code(formatReferenceFull(result.data, detail)));
break;
}
case 'docs.detail.section': {
- humanLog(formatSection(result.data, detail));
+ emit(code(formatSection(result.data, detail)));
break;
}
}
diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjs
index df45a109e8..4811ac86de 100644
--- a/packages/cli/clients/cli/commands/doctor.mjs
+++ b/packages/cli/clients/cli/commands/doctor.mjs
@@ -11,45 +11,51 @@
*/
import {runChecks} from '../../../api/doctor/doctor.mjs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, records, text} from '../formatters/index.mjs';
-/** Status → human glyph (monochrome, matching the rest of the CLI). */
-const GLYPH = {
- pass: '\u2713', // ✓
- warn: '\u26a0', // ⚠
- fail: '\u2717', // ✗
- info: '\u2139', // ℹ
+/** Status -> ASCII token (plain, matching the rest of the CLI). */
+const STATUS = {
+ pass: '[ok]',
+ warn: '[warn]',
+ fail: '[fail]',
+ info: '[info]',
};
+/** @param {string} status */
+function statusToken(status) {
+ return STATUS[/** @type {keyof typeof STATUS} */ (status)] ?? status;
+}
+
/**
- * Render the report as a human-readable checklist.
+ * Render the report as a human-readable checklist. Each check is a record whose
+ * fields mirror the JSON (status/label/message/fix); the status glyph is an
+ * ASCII token so the output is byte-deterministic in any terminal.
* @param {import('../../../api/doctor/doctor.mjs').DoctorReport} report
*/
function printHuman(report) {
- humanLog('astryx doctor — diagnosing your setup\n');
- for (const check of report.checks) {
- const glyph = GLYPH[check.status] ?? '\u00b7';
- humanLog(` ${glyph} ${check.label}`);
- humanLog(` ${check.message}`);
- if (check.fix) {
- humanLog(` \u2192 fix: ${check.fix}`);
- }
- }
-
const {pass, warn, fail, info} = report.summary;
- humanLog('');
- humanLog(
- `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
- `${fail} failure${fail === 1 ? '' : 's'}` +
- (info ? `, ${info} info` : ''),
+ const closing =
+ fail > 0
+ ? 'Some checks failed. Address the items marked [fail] above.'
+ : warn > 0
+ ? 'No failures — but review the [warn] warnings above when you can.'
+ : 'All checks passed. Your XDS setup looks healthy.';
+
+ emit(
+ section('astryx doctor — diagnosing your setup'),
+ records(report.checks, {
+ fields: ['status', 'label', 'message', 'fix'],
+ labels: {label: 'check'},
+ format: {status: statusToken},
+ }),
+ text(
+ `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
+ `${fail} failure${fail === 1 ? '' : 's'}` +
+ (info ? `, ${info} info` : ''),
+ ),
+ text(closing),
);
- if (fail > 0) {
- humanLog('\nSome checks failed. Address the items marked \u2717 above.');
- } else if (warn > 0) {
- humanLog('\nNo failures — but review the \u26a0 warnings above when you can.');
- } else {
- humanLog('\nAll checks passed. Your XDS setup looks healthy.');
- }
}
/**
diff --git a/packages/cli/clients/cli/commands/hook/index.mjs b/packages/cli/clients/cli/commands/hook/index.mjs
index 22124ba54f..1ee308328d 100644
--- a/packages/cli/clients/cli/commands/hook/index.mjs
+++ b/packages/cli/clients/cli/commands/hook/index.mjs
@@ -13,7 +13,8 @@ import {
formatHookParams,
} from '../../lib/hook-format.mjs';
import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';
-import {jsonOut, humanLog} from '../../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../../foundation/response/json.mjs';
+import {emit, section, text, list, records, code} from '../../formatters/index.mjs';
import {cliError} from '../../lib/cli-error.mjs';
import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
import {hook as hookApi} from '../../../../api/hook/hook.mjs';
@@ -88,64 +89,66 @@ export function registerHook(program) {
if (result.data.detail === 'full') {
// --detail full — dense per-hook docs grouped by category
// (import block, best practices, full params + returns tables, related).
+ // The whole view is one markdown document: a `## <category>` heading
+ // over each category's concatenated hook docs.
const groups = result.data.components;
- humanLog('');
+ /** @type {import('../../formatters/index.mjs').Block[]} */
+ const out = [];
for (const [cat, items] of Object.entries(groups)) {
- humanLog(`## ${cat}\n`);
- for (const item of items) {
- const importPath = item.importPath || '@astryxdesign/core/hooks';
- humanLog(formatHookCompact(item, importPath));
- }
+ const body = items
+ .map(item =>
+ formatHookCompact(item, item.importPath || '@astryxdesign/core/hooks'),
+ )
+ .join('\n');
+ out.push(code(`## ${cat}\n\n${body}`));
}
+ emit(...out);
break;
}
if (result.data.detail === 'compact') {
- // --detail compact — name + 1-line description per entry.
+ // --detail compact — one record (name + description) per hook,
+ // grouped by category.
const groups = result.data.components;
- humanLog('');
+ /** @type {import('../../formatters/index.mjs').Block[]} */
+ const out = [];
for (const [cat, items] of Object.entries(groups)) {
- humanLog(cat);
- for (const item of items) {
- const desc = item.description ? ` — ${item.description}` : '';
- humanLog(` ${item.name}${desc}`);
- }
- humanLog('');
+ out.push(section(cat), records(items, {fields: ['name', 'description']}));
}
- humanLog(`Usage: ${run} hook <name>`);
- humanLog('');
+ out.push(text(`Usage: ${run} hook <name>`));
+ emit(...out);
break;
}
- // --detail names (default for list views) — names only.
+ // --detail names (default for list views) — names only, grouped by
+ // category.
const groups = result.data.components;
if (options.category) {
const [cat, hookNames] = Object.entries(groups)[0];
- humanLog(`\n${cat}:`);
- for (const h of hookNames) humanLog(` ${h}`);
- humanLog('');
+ emit(section(`${cat}:`), list(hookNames));
} else {
- humanLog('');
+ /** @type {import('../../formatters/index.mjs').Block[]} */
+ const out = [];
for (const [category, hookNames] of Object.entries(groups)) {
- humanLog(category);
- for (const h of hookNames) humanLog(` ${h}`);
+ out.push(section(category), list(hookNames));
}
- humanLog('');
- humanLog(`Usage: ${run} hook <name>`);
- humanLog('');
+ out.push(text(`Usage: ${run} hook <name>`));
+ emit(...out);
}
break;
}
case 'hook.detail': {
- if (detail === 'brief') {
- humanLog(formatHookBrief(result.data));
- } else if (detail === 'compact') {
- const importPath = result.data.importPath || '@astryxdesign/core/hooks';
- humanLog(formatHookCompact(result.data, importPath));
- } else {
- humanLog(formatHookFull(result.data));
- }
+ const doc =
+ detail === 'brief'
+ ? formatHookBrief(result.data)
+ : detail === 'compact'
+ ? formatHookCompact(
+ result.data,
+ result.data.importPath || '@astryxdesign/core/hooks',
+ )
+ : formatHookFull(result.data);
+
// Show related block templates from relatedComponents
const relatedComps = result.data.relatedComponents || [];
/** @type {import('../../../../api/template/template.mjs').DiscoveredTemplate[]} */
@@ -158,19 +161,18 @@ export function registerHook(program) {
}
}
}
- if (allBlocks.length > 0) {
- humanLog('\nRelated block templates:\n');
- for (const b of allBlocks) {
- humanLog(` ${b.dirName}`);
- if (b.description) humanLog(` ${b.description}`);
- }
- humanLog('');
- }
+
+ emit(
+ code(doc),
+ allBlocks.length > 0 && section('Related block templates'),
+ allBlocks.length > 0 &&
+ records(allBlocks, {fields: ['dirName', 'description']}),
+ );
break;
}
case 'hook.detail.params': {
- humanLog(formatHookParams({params: result.data, name: name}));
+ emit(code(formatHookParams({params: result.data, name})));
break;
}
}
diff --git a/packages/cli/clients/cli/commands/layout.mjs b/packages/cli/clients/cli/commands/layout.mjs
index df49a4c138..2e0b9ff541 100644
--- a/packages/cli/clients/cli/commands/layout.mjs
+++ b/packages/cli/clients/cli/commands/layout.mjs
@@ -14,7 +14,8 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, code, WARN} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {layoutExpand, layoutCheck, layoutGrammar} from '../../../api/layout/layout.mjs';
@@ -136,17 +137,30 @@ export function registerLayout(program) {
}
if (json) return jsonOut(result);
- for (const warning of result.data.warnings) humanLog(`⚠ ${warning}`);
+ /** @type {import('../formatters/index.mjs').Block[]} */
+ const out = [];
+ if (result.data.warnings.length > 0) {
+ out.push(text(result.data.warnings.map(w => `${WARN} ${w}`).join('\n')));
+ }
if (result.data.written) {
- humanLog(`\n✓ Expanded to ${result.data.written}`);
- humanLog(` Components: ${result.data.componentsUsed.join(', ')}`);
- if (result.data.todos.length > 0) {
- humanLog(` TODOs: ${result.data.todos.length} (search for "TODO(xle)")`);
- }
- humanLog('');
+ out.push(
+ text(`[ok] Expanded to ${result.data.written}`),
+ record(
+ {
+ components: result.data.componentsUsed,
+ todos:
+ result.data.todos.length > 0
+ ? `${result.data.todos.length} (search for "TODO(xle)")`
+ : '',
+ },
+ {labels: {components: 'Components', todos: 'TODOs'}},
+ ),
+ );
} else {
- humanLog(result.data.code);
+ // Raw expanded TSX (no target path) — preformatted, emitted verbatim.
+ out.push(code(result.data.code));
}
+ emit(...out);
});
layoutCmd
@@ -188,21 +202,27 @@ export function registerLayout(program) {
const {valid, form, errors, warnings, compact, outline} = result.data;
if (!valid) {
- humanLog(`\n✗ Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`);
- for (const e of errors) {
- humanLog(` - ${e.formatted}`);
- if (e.suggestions && e.suggestions.length > 0) humanLog(` did you mean: ${e.suggestions.join(', ')}?`);
- }
- humanLog('');
+ // Each error: the formatted issue, with a hanging "did you mean" line.
+ const items = errors.map(e =>
+ e.suggestions && e.suggestions.length > 0
+ ? [e.formatted, `did you mean: ${e.suggestions.join(', ')}?`]
+ : [e.formatted],
+ );
+ emit(
+ text(`[fail] Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`),
+ list(items),
+ );
return;
}
- humanLog(`\n✓ Valid (parsed as ${form})`);
- for (const warning of warnings) humanLog(`⚠ ${warning}`);
- humanLog('\ncompact:');
- humanLog(` ${compact}`);
- humanLog('\noutline:');
- humanLog(outline.split('\n').map(l => ` ${l}`).join('\n'));
- humanLog('');
+
+ /** @type {import('../formatters/index.mjs').Block[]} */
+ const out = [text(`[ok] Valid (parsed as ${form})`)];
+ if (warnings.length > 0) {
+ out.push(text(warnings.map(w => `${WARN} ${w}`).join('\n')));
+ }
+ // The canonical compact/outline surfaces are preformatted — emit verbatim.
+ out.push(section('compact'), code(compact), section('outline'), code(outline));
+ emit(...out);
});
layoutCmd
@@ -220,6 +240,7 @@ export function registerLayout(program) {
return;
}
if (json) return jsonOut(result);
- humanLog(result.data.text);
+ // The cheatsheet is a preformatted document — emit verbatim.
+ emit(code(result.data.text));
});
}
diff --git a/packages/cli/clients/cli/commands/search.mjs b/packages/cli/clients/cli/commands/search.mjs
index fef3c28a61..b7368b3c76 100644
--- a/packages/cli/clients/cli/commands/search.mjs
+++ b/packages/cli/clients/cli/commands/search.mjs
@@ -17,17 +17,11 @@
*/
import {getCliInvocation, formatCliCommand} from '../../../foundation/env/package-manager.mjs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, records} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {search as searchApi, SEARCH_DOMAINS} from '../../../api/search/search.mjs';
-const DOMAIN_LABEL = {
- component: 'component',
- hook: 'hook',
- doc: 'docs',
- template: 'template',
-};
-
/**
* @param {import('commander').Command} program
*/
@@ -71,31 +65,24 @@ export function registerSearch(program) {
// No matches is a valid, successful outcome — clean message, exit 0.
if (results.length === 0) {
- humanLog('');
- humanLog(`No results for "${q}".`);
- humanLog('');
- humanLog(`Try a broader term, or browse: ${run} component --list`);
- humanLog('');
+ emit(
+ text(`No results for "${q}".`),
+ text(`Try a broader term, or browse: ${run} component --list`),
+ );
return;
}
- humanLog('');
- humanLog(`Results for "${q}" (${results.length}):`);
- humanLog('');
- for (const r of results) {
- const tag = `[${DOMAIN_LABEL[r.domain] || r.domain}]`.padEnd(12);
- const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
- humanLog(` ${tag} ${display}`);
- if (r.description) {
- humanLog(` ${r.description}`);
- }
- humanLog(` → ${formatCliCommand(r.command)}`);
- if (options.verbose) {
- if (r.import) humanLog(` import: ${r.import}`);
- humanLog(` match: ${r.reason} (score ${r.score})`);
- }
- humanLog('');
- }
+ // The text view is just a projection of the JSON: one record per result,
+ // fields in a fixed order (missing ones skipped), command prefixed for the
+ // caller's package manager. Ranked order is preserved (best match first).
+ const fields = options.verbose
+ ? ['name', 'domain', 'displayName', 'score', 'reason', 'import', 'description', 'command']
+ : ['name', 'domain', 'displayName', 'import', 'description', 'command'];
+
+ emit(
+ section(`Results for "${q}" (${results.length})`),
+ records(results, {fields, format: {command: formatCliCommand}}),
+ );
});
}
diff --git a/packages/cli/clients/cli/commands/search.test.mjs b/packages/cli/clients/cli/commands/search.test.mjs
index 8a87039ffc..a4731923f8 100644
--- a/packages/cli/clients/cli/commands/search.test.mjs
+++ b/packages/cli/clients/cli/commands/search.test.mjs
@@ -191,10 +191,13 @@ describe('search CLI — exit codes + JSON contract', () => {
expect(parsed.data.results).toEqual([]);
});
- it('shows the follow-up command hint in human output', async () => {
+ it('renders each result as a greppable key: value record', async () => {
const r = await runCli(['search', 'button'], REPO_ROOT);
expect(r.stdout).toContain('astryx component Button');
- expect(r.stdout).toContain('[component]');
+ // Fields mirror the JSON object and are line-greppable.
+ expect(r.stdout).toMatch(/^name:\s+Button$/m);
+ expect(r.stdout).toMatch(/^domain:\s+component$/m);
+ expect(r.stdout).toContain('description:');
});
it('--verbose exits 0 and prints import/match detail', async () => {
@@ -205,6 +208,9 @@ describe('search CLI — exit codes + JSON contract', () => {
const r = await runCli(['search', 'button', '--verbose'], REPO_ROOT);
expect(r.status).toBe(0);
expect(r.stdout).toContain('import:');
- expect(r.stdout).toContain('match:');
+ // Ranking detail: pre-formatter this was a single `match: <reason> (score N)`
+ // line; it's now separate `score:` / `reason:` record fields mirroring --json.
+ expect(r.stdout).toContain('score:');
+ expect(r.stdout).toContain('reason:');
});
}, SCAN_TIMEOUT);
diff --git a/packages/cli/clients/cli/commands/swizzle.mjs b/packages/cli/clients/cli/commands/swizzle.mjs
index 4dbc0b024c..a48ac2fba6 100644
--- a/packages/cli/clients/cli/commands/swizzle.mjs
+++ b/packages/cli/clients/cli/commands/swizzle.mjs
@@ -10,7 +10,8 @@
* commands for the caller's package manager.
*/
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, list, text, WARN} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {swizzle as swizzleApi} from '../../../api/swizzle/swizzle.mjs';
@@ -50,54 +51,63 @@ export function registerSwizzle(program) {
if (result.type === 'swizzle.list') {
const components = result.data;
- humanLog('\nAvailable components:\n');
- for (const name of components) {
- humanLog(` ${name}`);
- }
- humanLog(`\nUsage: ${run} swizzle <component>\n`);
- humanLog(`Example: ${run} swizzle Button`);
- humanLog(` ${run} swizzle XDSButton (XDS prefix also works)\n`);
+ emit(
+ section('Available components'),
+ list(components),
+ text(`Usage: ${run} swizzle <component>`),
+ text(
+ [
+ `Example: ${run} swizzle Button`,
+ ` ${run} swizzle XDSButton (XDS prefix also works)`,
+ ].join('\n'),
+ ),
+ );
return;
}
const {package: ownerPackage, outputDir, filesCopied, usesStyleX, feedback} =
result.data;
- humanLog(`\n✓ Copied ${filesCopied} files to ${outputDir}/\n`);
- humanLog(`Relative imports have been rewritten to use ${ownerPackage}.`);
- humanLog('You can now customize the component source freely.\n');
+ /** @type {import('../formatters/index.mjs').Block[]} */
+ const out = [
+ text(`[ok] Copied ${filesCopied} files to ${outputDir}/`),
+ text(
+ [
+ `Relative imports have been rewritten to use ${ownerPackage}.`,
+ 'You can now customize the component source freely.',
+ ].join('\n'),
+ ),
+ ];
// StyleX build requirement — swizzled StyleX source renders unstyled with
// no error unless the consumer's build runs a StyleX compiler.
if (usesStyleX) {
- humanLog(
- '⚠ These components use StyleX and require a StyleX compiler in your build.',
- );
- humanLog(
- ' Without one they render unstyled (no error). See setup per framework:',
- );
- humanLog(` ${run} docs styling`);
- humanLog(
- ' Next.js note: the StyleX Babel plugin disables SWC and breaks next/font —',
+ out.push(
+ text(
+ [
+ `${WARN} These components use StyleX and require a StyleX compiler in your build.`,
+ ' Without one they render unstyled (no error). See setup per framework:',
+ ` ${run} docs styling`,
+ ' Next.js note: the StyleX Babel plugin disables SWC and breaks next/font -',
+ ' use an SWC-based StyleX transform instead (covered in the guide).',
+ ].join('\n'),
+ ),
);
- humanLog(
- ' use an SWC-based StyleX transform instead (covered in the guide).',
- );
- humanLog('');
}
// Maintainer feedback note (skipped when the owner ships no issues URL).
if (feedback) {
- humanLog(
- 'Customizing a component often signals a gap in the design system.',
+ out.push(
+ text(
+ [
+ 'Customizing a component often signals a gap in the design system.',
+ 'Let the maintainers know what you needed:',
+ ` ${feedback.ghCommand || feedback.issuesUrl}`,
+ ].join('\n'),
+ ),
);
- humanLog('Let the maintainers know what you needed:');
- if (feedback.ghCommand) {
- humanLog(` ${feedback.ghCommand}`);
- } else {
- humanLog(` ${feedback.issuesUrl}`);
- }
- humanLog('');
}
+
+ emit(...out);
});
}
diff --git a/packages/cli/clients/cli/commands/template.mjs b/packages/cli/clients/cli/commands/template.mjs
index fb8d518dd3..a36d41a0b4 100644
--- a/packages/cli/clients/cli/commands/template.mjs
+++ b/packages/cli/clients/cli/commands/template.mjs
@@ -6,7 +6,8 @@
import * as path from 'node:path';
import * as fs from 'node:fs';
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, records, code} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {template as templateApi} from '../../../api/template/template.mjs';
@@ -126,48 +127,59 @@ export function registerTemplate(program) {
case 'template.list': {
const pages = result.data.filter(t => t.type === 'page');
const blocks = result.data.filter(t => t.type === 'block');
+ // Project each entry to its JSON-mirroring fields; the WIP marker is
+ // folded into `name` (as before) and the package is shown only when it
+ // isn't the built-in core package.
/** @param {import('../../../api/template/template.type.mjs').TemplateListEntry} t */
- const renderEntry = t => {
- const status = t.isReady ? '' : ' (WIP)';
- const pkg =
- t.package && t.package !== '@astryxdesign/core'
- ? ` [${t.package}]`
- : '';
- humanLog(` ${t.name}${status}${pkg}`);
- if (t.description) humanLog(` ${t.description}`);
- };
- if (pages.length > 0) {
- humanLog('\nPage Templates:\n');
- for (const t of pages) renderEntry(t);
- }
- if (blocks.length > 0) {
- humanLog('\nBlock Templates:\n');
- for (const t of blocks) renderEntry(t);
- }
- humanLog('\nUsage:');
- humanLog(` ${run} template <id> [target-path] Scaffold page or block`);
- humanLog(` ${run} template <id> --skeleton Layout reference`);
- humanLog(` ${run} template --list --type block List only blocks`);
- humanLog(` ${run} template --list --package <pkg> List from one package\n`);
+ const toRow = t => ({
+ name: t.isReady ? t.name : `${t.name} (WIP)`,
+ description: t.description,
+ package:
+ t.package && t.package !== '@astryxdesign/core' ? t.package : '',
+ });
+ const fields = ['name', 'description', 'package'];
+ emit(
+ pages.length > 0 && section('Page Templates'),
+ pages.length > 0 && records(pages.map(toRow), {fields}),
+ blocks.length > 0 && section('Block Templates'),
+ blocks.length > 0 && records(blocks.map(toRow), {fields}),
+ section('Usage'),
+ text(
+ [
+ `${run} template <id> [target-path] Scaffold page or block`,
+ `${run} template <id> --skeleton Layout reference`,
+ `${run} template --list --type block List only blocks`,
+ `${run} template --list --package <pkg> List from one package`,
+ ].join('\n'),
+ ),
+ );
break;
}
case 'template.skeleton': {
const {template: tName, description, components, skeleton} = result.data;
- humanLog(`\n# ${tName}${description ? ' — ' + description : ''}`);
- humanLog(`# Components: ${components.join(', ')}\n`);
- humanLog(skeleton);
- humanLog('');
+ emit(
+ text(
+ `# ${tName}${description ? ' — ' + description : ''}\n` +
+ `# Components: ${components.join(', ')}`,
+ ),
+ code(skeleton),
+ );
break;
}
case 'template.show': {
- humanLog(result.data.source);
+ // Source must survive piping byte-for-byte.
+ emit(code(result.data.source));
break;
}
case 'template.copy': {
- humanLog(`\n✓ Copied template to ${result.data.outputDir}/${result.data.fileName}\n`);
+ emit(
+ text(
+ `Copied template to ${result.data.outputDir}/${result.data.fileName}`,
+ ),
+ );
break;
}
}
diff --git a/packages/cli/clients/cli/commands/validate-integration.mjs b/packages/cli/clients/cli/commands/validate-integration.mjs
index 0ca04fadd3..9014417a08 100644
--- a/packages/cli/clients/cli/commands/validate-integration.mjs
+++ b/packages/cli/clients/cli/commands/validate-integration.mjs
@@ -14,7 +14,8 @@
* an integration package is not a failure).
*/
-import {jsonOut, humanLog} from '../../../foundation/response/json.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, records} from '../formatters/index.mjs';
import {
validateIntegration,
summarizeIssues,
@@ -27,21 +28,24 @@ import {
function printHuman(data) {
const label =
data.version != null ? `${data.name}@${data.version}` : data.name;
- humanLog(`Validating integration: ${label}`);
if (data.issues.length === 0) {
- humanLog('\n\u2713 No issues found.');
+ emit(
+ section(`Validating integration: ${label}`),
+ text('[ok] No issues found.'),
+ );
return;
}
- humanLog('');
- for (const issue of data.issues) {
- humanLog(` ${issue.severity} ${issue.code}: ${issue.message}`);
- }
-
+ // The issue list is a projection of the JSON: one record per issue, fields
+ // mirroring the JSON keys (severity/code/message).
const {errors, warnings} = summarizeIssues(data.issues);
- humanLog(
- `\n${data.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
+ emit(
+ section(`Validating integration: ${label}`),
+ records(data.issues, {fields: ['severity', 'code', 'message']}),
+ text(
+ `${data.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
+ ),
);
}
@@ -77,7 +81,7 @@ export function registerValidateIntegration(program) {
jsonOut(result);
} else if (result.data.name === null) {
// No-arg + no local manifest: guidance, not an error.
- humanLog(NO_MANIFEST_GUIDANCE);
+ emit(text(NO_MANIFEST_GUIDANCE));
} else {
printHuman(result.data);
}
diff --git a/packages/cli/clients/cli/formatters/index.mjs b/packages/cli/clients/cli/formatters/index.mjs
new file mode 100644
index 0000000000..8947b1c1c8
--- /dev/null
+++ b/packages/cli/clients/cli/formatters/index.mjs
@@ -0,0 +1,219 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The CLI's human-output formatters.
+ *
+ * The mental model: `--json` is the source of truth, and the plain-text output
+ * is just a human-readable projection of that same JSON. So the core renderers
+ * take JSON-native values (objects, arrays of objects, string arrays) directly
+ * and turn them into readable text — a command shouldn't have to hand-map every
+ * field. `record(obj)` / `records(arr)` are the workhorses; you mostly just pick
+ * which fields to show and in what order.
+ *
+ * Constraints (deliberately narrow):
+ * - Plain ASCII only. No color, no TTY detection, no width wrapping. Output is
+ * byte-for-byte deterministic whether printed or piped to an agent.
+ * - Renderers return an opaque {@link Block}; `emit` accepts ONLY Blocks, so a
+ * stray string can't leak onto stdout (the compiler rejects `emit('x')`).
+ * `emit` is the one stdout sink; errors/warnings go to stderr via
+ * cli-error.mjs, never here.
+ * - Field names in the text mirror the JSON keys 1:1, so every field is
+ * greppable (`grep '^description:'`) and the two views stay in sync.
+ */
+
+import {humanLog} from '../../../foundation/response/json.mjs';
+
+/**
+ * Shared ASCII vocabulary — used here and by stderr diagnostics (cli-error.mjs)
+ * so the whole CLI speaks one plain-text dialect. ASCII on purpose: renders
+ * identically in every terminal, pager, and captured log.
+ */
+export const ARROW = '->';
+export const BULLET = '-';
+export const ERR = '!!';
+export const WARN = '!';
+
+/**
+ * An opaque, renderer-produced block of output. Nominal via a private field:
+ * nothing outside this file can construct one, so `emit` can trust that whatever
+ * it receives came from a renderer (a plain string is not assignable to Block).
+ */
+export class Block {
+ /** @type {string} */
+ #text;
+ /** @param {string} text */
+ constructor(text) {
+ this.#text = text;
+ }
+ /** @returns {string} */
+ toString() {
+ return this.#text;
+ }
+}
+
+/**
+ * Anything `emit` accepts: a Block, or a falsy value so callers can inline
+ * conditionals (`cond && section(...)`). Falsy entries are dropped; a raw string
+ * is intentionally NOT assignable.
+ * @typedef {Block | false | null | undefined} Emittable
+ */
+
+/**
+ * Options shared by {@link record} and {@link records}.
+ * @typedef {object} RecordOptions
+ * @property {string[]} [fields] - Keys to show, in order. Missing/empty keys are
+ * skipped. Defaults to the object's own keys.
+ * @property {string[]} [omit] - Keys to exclude (when `fields` is not given).
+ * @property {Record<string, string>} [labels] - Rename a key for display.
+ * @property {Record<string, (value: any) => string>} [format] - Transform a
+ * value before rendering (e.g. prefix a command with the package manager).
+ */
+
+/** @param {unknown} v @returns {boolean} */
+function isEmpty(v) {
+ return (
+ v === null ||
+ v === undefined ||
+ v === '' ||
+ (Array.isArray(v) && v.length === 0)
+ );
+}
+
+/** @param {unknown} v @returns {string} */
+function renderValue(v) {
+ if (Array.isArray(v)) return v.map(x => String(x)).join(', ');
+ return String(v);
+}
+
+/**
+ * Normalize common non-ASCII typography to ASCII so human output stays plain and
+ * consistent no matter what the source data contains (em/en dashes -> "-", curly
+ * quotes -> straight, ellipsis -> "...", non-breaking space -> space). The
+ * the verbatim renderer (code) deliberately skips this. `--json` is
+ * unaffected — it always carries the original data.
+ * @param {string} s
+ * @returns {string}
+ */
+function toAscii(s) {
+ return String(s)
+ .replace(/[\u2014\u2013]/g, '-')
+ .replace(/[\u2018\u2019]/g, "'")
+ .replace(/[\u201C\u201D]/g, '"')
+ .replace(/\u2026/g, '...')
+ .replace(/\u00a0/g, ' ');
+}
+
+/**
+ * A group label, optionally with an explanatory subtitle rendered on the line(s)
+ * directly beneath the heading (no blank line between). Whatever list/records
+ * follow are separate blocks, so emit's blank line separates them from the
+ * header + subtitle.
+ * @param {string} heading
+ * @param {string} [subtitle]
+ * @returns {Block}
+ */
+export function section(heading, subtitle) {
+ return new Block(toAscii(subtitle ? `${heading}\n${subtitle}` : String(heading)));
+}
+
+/**
+ * A prose block, printed as-is (no wrapping). Multi-line strings kept verbatim.
+ * @param {string} content
+ * @returns {Block}
+ */
+export function text(content) {
+ return new Block(toAscii(String(content)));
+}
+
+/**
+ * A bulleted list of primitives (e.g. a string array). Each item is a string or
+ * an array of lines (first line is the head, the rest hang-indent). For arrays
+ * of OBJECTS use {@link records} instead.
+ * @param {Array<string | string[]>} items
+ * @returns {Block}
+ */
+export function list(items) {
+ const hang = ' '.repeat(BULLET.length + 1);
+ const rendered = items.map(item => {
+ const lines = Array.isArray(item) ? item : String(item).split('\n');
+ const [head = '', ...rest] = lines;
+ return [`${BULLET} ${head}`, ...rest.map(l => `${hang}${l}`)].join('\n');
+ });
+ const multiline = rendered.some(r => r.includes('\n'));
+ return new Block(toAscii(rendered.join(multiline ? '\n\n' : '\n')));
+}
+
+/**
+ * Render a JSON object as aligned `key: value` lines — the readable projection
+ * of that object. Values: strings as-is, arrays comma-joined, other primitives
+ * String()'d; empty/missing fields are skipped. Field names mirror the JSON keys
+ * so the output is greppable and maps 1:1 to `--json`.
+ * @param {any} obj
+ * @param {RecordOptions} [options]
+ * @returns {Block}
+ */
+export function record(obj, options = {}) {
+ const src = /** @type {Record<string, unknown>} */ (obj);
+ const keys = (options.fields ?? Object.keys(src)).filter(
+ k => !options.omit?.includes(k) && !isEmpty(src[k]),
+ );
+ /** @param {string} k */
+ const label = k => options.labels?.[k] ?? k;
+ const keyWidth = keys.reduce((max, k) => Math.max(max, label(k).length), 0);
+ const lines = keys.map(k => {
+ const fmt = options.format?.[k];
+ const value = fmt ? fmt(src[k]) : renderValue(src[k]);
+ return `${`${label(k)}:`.padEnd(keyWidth + 2)}${value}`;
+ });
+ return new Block(toAscii(lines.join('\n')));
+}
+
+/**
+ * Render an array of JSON objects as {@link record}s, one per object, separated
+ * by a blank line. The single easiest way to turn `data.results` (or any object
+ * array) into readable text.
+ * @param {any[]} items
+ * @param {RecordOptions} [options]
+ * @returns {Block}
+ */
+export function records(items, options = {}) {
+ const blocks = items.map(o => record(o, options).toString()).filter(Boolean);
+ return new Block(blocks.join('\n\n'));
+}
+
+/**
+ * A verbatim block — source dumps, layout skeletons, or a markdown doc. Output
+ * is byte-for-byte (NOT ASCII-normalized), so it survives piping
+ * (`astryx template X > file.tsx`) and preserves doc/source content exactly.
+ * @param {string} source
+ * @param {{lang?: string}} [_options] - Reserved (intent label); output verbatim.
+ * @returns {Block}
+ */
+export function code(source, _options = {}) {
+ return new Block(String(source));
+}
+
+/**
+ * @param {Emittable} b
+ * @returns {b is Block}
+ */
+function isBlock(b) {
+ return b instanceof Block;
+}
+
+/**
+ * The one sanctioned way to write human output to stdout. Joins blocks with a
+ * single blank line and hands the result to `humanLog`, which is a no-op in
+ * `--json` mode (stdout carries only the envelope there). Accepts only Blocks
+ * (plus falsy placeholders); a bare string will not type-check.
+ * @param {Emittable[]} blocks
+ * @returns {void}
+ */
+export function emit(...blocks) {
+ const body = blocks
+ .filter(isBlock)
+ .map(b => b.toString())
+ .filter(s => s.length > 0)
+ .join('\n\n');
+ humanLog(body);
+}
diff --git a/packages/cli/clients/cli/formatters/index.test.mjs b/packages/cli/clients/cli/formatters/index.test.mjs
new file mode 100644
index 0000000000..efc1a518ee
--- /dev/null
+++ b/packages/cli/clients/cli/formatters/index.test.mjs
@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {
+ emit,
+ section,
+ text,
+ list,
+ record,
+ records,
+ code,
+ Block,
+ BULLET,
+ ARROW,
+} from './index.mjs';
+import {setJsonMode} from '../../../foundation/response/json.mjs';
+
+afterEach(() => {
+ setJsonMode(false);
+ vi.restoreAllMocks();
+});
+
+describe('constants', () => {
+ it('are plain ASCII', () => {
+ expect(BULLET).toBe('-');
+ expect(ARROW).toBe('->');
+ expect(/[^\x20-\x7E]/.test(`${BULLET}${ARROW}`)).toBe(false);
+ });
+});
+
+describe('renderers return Block', () => {
+ it('produces nominal Block instances', () => {
+ expect(section('x')).toBeInstanceOf(Block);
+ expect(record({a: 1})).toBeInstanceOf(Block);
+ expect(records([{a: 1}])).toBeInstanceOf(Block);
+ expect(code('a')).toBeInstanceOf(Block);
+ });
+});
+
+describe('section', () => {
+ it('renders a heading alone, or heading + subtitle directly beneath', () => {
+ expect(section('PAGE TEMPLATES').toString()).toBe('PAGE TEMPLATES');
+ expect(section('PAGE TEMPLATES', 'Closest full-page templates.').toString()).toBe(
+ 'PAGE TEMPLATES\nClosest full-page templates.',
+ );
+ });
+});
+
+describe('list', () => {
+ it('renders single-line items tightly with bullets', () => {
+ expect(list(['alpha', 'beta']).toString()).toBe('- alpha\n- beta');
+ });
+
+ it('hang-indents multi-line items and separates them with a blank line', () => {
+ expect(list([['head', 'detail'], 'solo']).toString()).toBe(
+ '- head\n detail\n\n- solo',
+ );
+ });
+});
+
+describe('record', () => {
+ it('renders a JSON object as aligned key: value lines', () => {
+ const lines = record({
+ name: 'Button',
+ domain: 'component',
+ description: 'A button.',
+ })
+ .toString()
+ .split('\n');
+ expect(lines[0]).toMatch(/^name:\s+Button$/);
+ expect(lines[1]).toMatch(/^domain:\s+component$/);
+ expect(lines[2]).toMatch(/^description: A button\.$/);
+ // Values align to one column (keyWidth 'description' = 11, +2 = 13).
+ expect(lines[0].indexOf('Button')).toBe(13);
+ expect(lines[2].indexOf('A button.')).toBe(13);
+ });
+
+ it('picks + orders fields and skips missing/empty ones', () => {
+ const out = record(
+ {name: 'X', domain: 'component', description: ''},
+ {fields: ['domain', 'name', 'displayName', 'description']},
+ ).toString();
+ expect(out).toBe('domain: component\nname: X');
+ });
+
+ it('applies labels and format transforms', () => {
+ const out = record(
+ {command: 'astryx x'},
+ {labels: {command: 'run'}, format: {command: v => `pnpm exec ${v}`}},
+ ).toString();
+ expect(out).toBe('run: pnpm exec astryx x');
+ });
+
+ it('joins array values with commas', () => {
+ expect(record({frame: ['AppShell', 'TopNav']}).toString()).toBe(
+ 'frame: AppShell, TopNav',
+ );
+ });
+});
+
+describe('records', () => {
+ it('renders one record per object separated by a blank line', () => {
+ expect(records([{name: 'A'}, {name: 'B'}]).toString()).toBe('name: A\n\nname: B');
+ });
+});
+
+describe('ASCII normalization', () => {
+ it('converts em/en dashes, curly quotes, and ellipsis in prose + records', () => {
+ expect(text('a \u2014 b').toString()).toBe('a - b');
+ expect(section('X \u2013 Y').toString()).toBe('X - Y');
+ expect(record({name: '\u201cSettings\u201d \u2014 Form\u2026'}).toString()).toBe(
+ 'name: "Settings" - Form...',
+ );
+ expect(list(['Avatar \u2014 Group']).toString()).toBe('- Avatar - Group');
+ });
+
+ it('leaves code verbatim (no normalization)', () => {
+ expect(code('a \u2014 b').toString()).toBe('a \u2014 b');
+ });
+});
+
+describe('code', () => {
+ it('is byte-for-byte verbatim (source or docs)', () => {
+ const src = 'const x = 1;\n const y = 2;\n';
+ expect(code(src).toString()).toBe(src);
+ expect(code('# Title\n\n- a\n').toString()).toBe('# Title\n\n- a\n');
+ });
+});
+
+describe('emit', () => {
+ it('joins blocks with a single blank line via one console.log', () => {
+ const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ emit(section('A'), text('B'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(spy).toHaveBeenCalledWith('A\n\nB');
+ });
+
+ it('drops falsy placeholders', () => {
+ const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ emit(section('A'), false, null, undefined, text('B'));
+ expect(spy).toHaveBeenCalledWith('A\n\nB');
+ });
+
+ it('is a no-op in --json mode (stdout stays clean)', () => {
+ const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+ setJsonMode(true);
+ emit(section('A'), text('B'));
+ expect(spy).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/cli/clients/cli/formatters/type-tests.mjs b/packages/cli/clients/cli/formatters/type-tests.mjs
new file mode 100644
index 0000000000..769bffc562
--- /dev/null
+++ b/packages/cli/clients/cli/formatters/type-tests.mjs
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Compile-time guards for the formatter contract. Never executed — its
+ * only job is to make `tsc` (checkJs + strict, via tsconfig.strict.json) prove
+ * that `emit` accepts renderer output and rejects raw strings. If any
+ * `@ts-expect-error` below stops erroring, the contract has regressed and the
+ * type check fails.
+ */
+
+import {emit, section, text, list, record, records, code} from './index.mjs';
+
+/** @returns {void} */
+export function __formatterTypeGuards() {
+ // Renderer output is emittable.
+ emit(section('s'), section('H', 'subtitle'), text('p'));
+ emit(list(['a', ['head', 'detail']]));
+ emit(record({name: 'Button', domain: 'component'}, {fields: ['name', 'domain']}));
+ emit(records([{name: 'A'}, {name: 'B'}], {format: {name: v => String(v)}}));
+ emit(code('const x = 1;'));
+
+ // Falsy placeholders are allowed (inline conditionals).
+ const show = false;
+ emit(section('s'), show && section('maybe'), null, undefined);
+
+ // @ts-expect-error a bare string is not a Block — must go through a renderer.
+ emit('raw string');
+
+ // @ts-expect-error a number is not a Block.
+ emit(42);
+}
diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjs
index fafd861a59..989cb81416 100644
--- a/packages/cli/clients/cli/index.mjs
+++ b/packages/cli/clients/cli/index.mjs
@@ -21,6 +21,7 @@ import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';
import {buildManifest} from './lib/manifest.mjs';
import {cliError} from './lib/cli-error.mjs';
+import {emit, section, text, records} from './formatters/index.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
import {installJsonShim} from './lib/json-shim.mjs';
@@ -135,6 +136,50 @@ const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
export async function createProgram() {
const program = new Command();
+ // Deterministic, single-line help. Commander wraps each option/command
+ // description to a column width (80 when captured non-TTY), which splits long
+ // descriptions like --json across several indented lines. Override `wrap` to a
+ // no-op so every item stays on one line — matching the rest of the CLI's
+ // plain, unwrapped, width-independent output. Set before subcommands are
+ // registered so they inherit it via copyInheritedSettings.
+ program.configureHelp({wrap: (str) => str});
+
+ // Document the text-output contract in --help so agents know how to parse/grep
+ // it (and when to reach for --json instead). Kept in sync with the formatter
+ // kit in clients/cli/formatters.
+ program.addHelpText(
+ 'after',
+ '\n' +
+ [
+ section(
+ 'Output format',
+ 'Text mirrors --json (the machine-readable surface); it is built from these blocks:',
+ ),
+ records(
+ [
+ {
+ block: 'Record',
+ shape: 'aligned "key: value" lines = one item; records separated by a blank line',
+ },
+ {
+ block: 'Section',
+ shape: 'a header line (no "key:"), optional one-line subtitle, then its records/list',
+ },
+ {block: 'List', shape: '"- value" lines for a simple sequence of values'},
+ {block: 'Text', shape: 'free-form prose / notes'},
+ {block: 'Code', shape: 'a verbatim block (source, skeleton, or doc), emitted exactly'},
+ ],
+ {fields: ['block', 'shape']},
+ ),
+ text(
+ 'Grep a field across records, e.g. astryx search button | grep "^command:". ' +
+ 'Errors/warnings go to stderr; use --json for structured parsing.',
+ ),
+ ]
+ .map(block => block.toString())
+ .join('\n\n'),
+ );
+
program
.name('astryx')
.description('Design system CLI — components, themes, and tooling')
@@ -360,14 +405,21 @@ export async function createProgram() {
console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
return;
}
- // Human-readable summary. Agents should use --json.
- console.log(`\n${manifest.name} v${manifest.version} — ${manifest.commands.length} commands\n`);
- for (const c of manifest.commands) {
- const tag = c.json ? ' [--json]' : '';
- console.log(` ${c.name}${tag}`);
- if (c.description) console.log(` ${c.description}`);
- }
- console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
+ // Human-readable summary as greppable records (agents should use --json).
+ // One record per command: name, whether it supports --json, and the
+ // description.
+ emit(
+ section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
+ records(
+ manifest.commands.map(c => ({
+ command: c.name,
+ json: c.json ? 'yes' : '',
+ description: c.description || '',
+ })),
+ {fields: ['command', 'json', 'description']},
+ ),
+ text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
+ );
});
// Hidden command used by package.json postinstall scripts