Skip to content

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

TypeScript

fix(cli): make every command's text output match its --json data (#6616)

Joeyb1da7d239b11
diff --git a/.changeset/fix-cli-text-json-parity.md b/.changeset/fix-cli-text-json-parity.md
new file mode 100644
index 0000000000..7d7d148bdd
--- /dev/null
+++ b/.changeset/fix-cli-text-json-parity.md
@@ -0,0 +1,16 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Make every command's text output match its --json data
+
+`upgrade --list` text now renders each codemod from the JSON result (name,
+title, version, optional) instead of the API logger, with no `(undefined)`
+rows. `theme targets` prints one line per target via the formatter kit's
+inline layout and now shows className. `docs` list shows the package field.
+A manifest-driven parity test covers the commands this PR fixes and catches
+future regressions in the same family; commands with known deferred
+divergences are covered by envelope and exit-code checks and have
+allowlist entries that explain the gap.
+
+@josephfarina
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index 8b1443cc18..cb90ea65f4 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.mjs
@@ -33,7 +33,7 @@ import {fileURLToPath} from 'node:url';
import {spawn} from 'node:child_process';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, text, list, code} from '../formatters/index.mjs';
+import {emit, section, text, list, records, code} from '../formatters/index.mjs';
import {logger} from '../../../api/logger.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -229,47 +229,6 @@ function printThemeList(themes) {
);
}
-/**
- * Render the targets as one greppable line each, under an aligned header. A
- * `records()` block would be five lines per target — over a thousand for the
- * full surface, which is the view this command exists to make readable.
- * @param {import('../../../api/theme/theme.type.mjs').ThemeTargetEntry[]} targets
- * @returns {string}
- */
-function formatTargetsTable(targets) {
- const rows = targets.map(t => ({
- key: t.deprecatedFor
- ? `${t.key} [deprecated; use ${t.deprecatedFor}]`
- : t.key,
- component: t.component,
- props: t.props.join(', ') || '-',
- states: t.states.join(', ') || '-',
- }));
- const head = {
- key: 'key',
- component: 'component',
- props: 'props',
- states: 'states',
- };
- const width = (/** @type {'key'|'component'|'props'} */ field) =>
- [head, ...rows].reduce((max, r) => Math.max(max, r[field].length), 0);
- const w = {
- key: width('key'),
- component: width('component'),
- props: width('props'),
- };
- const line = (/** @type {typeof head} */ r) =>
- [
- r.key.padEnd(w.key),
- r.component.padEnd(w.component),
- r.props.padEnd(w.props),
- r.states,
- ]
- .join(' ')
- .trimEnd();
- return [line(head), ...rows.map(line)].join('\n');
-}
-
/**
* @param {import('commander').Command} program
*/
@@ -811,9 +770,16 @@ export function registerTheme(program) {
emit(
section(
'Theming targets',
- `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}`,
+ `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}\n(key - component - props - states - className - deprecatedFor)`,
),
- text(formatTargetsTable(targets)),
+ records(targets, {
+ fields: ['key', 'component', 'props', 'states', 'className', 'deprecatedFor'],
+ layout: 'inline',
+ format: {
+ deprecatedFor: (/** @type {string|null} */ v) =>
+ v ? `deprecated; use ${v}` : '',
+ },
+ }),
text(
[
`Each key goes under \`components\` in defineTheme; it paints \`.astryx-<key>\`.`,
diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjs
index 4ee36f0095..048d2939b7 100644
--- a/packages/cli/clients/cli/commands/docs.mjs
+++ b/packages/cli/clients/cli/commands/docs.mjs
@@ -280,7 +280,7 @@ export function registerDocs(program) {
emit(
section('Available docs'),
records(result.data, {
- fields: ['topic', 'description'],
+ fields: ['topic', 'description', 'package'],
layout: 'inline',
}),
text(
diff --git a/packages/cli/clients/cli/commands/text-json-parity.test.mjs b/packages/cli/clients/cli/commands/text-json-parity.test.mjs
new file mode 100644
index 0000000000..6f51834491
--- /dev/null
+++ b/packages/cli/clients/cli/commands/text-json-parity.test.mjs
@@ -0,0 +1,719 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Text/JSON parity — every command's human output is a projection of its
+ * JSON envelope.
+ *
+ * Architecture: cli-surface INV4, INV5. Spec: AST-042 FR1.
+ *
+ * The test:
+ * 1. Enumerates every JSON-capable command from the live manifest and fails
+ * when a command has no parity case. A new command must add one.
+ * 2. Runs each case in text mode and --json mode via the in-process harness.
+ * 3. Checks:
+ * a. Every `key: value` record line in the text names a key that exists
+ * in the JSON data (criterion 1 — text shows no fact JSON lacks).
+ * b. Every JSON leaf field appears in the text, unless the allowlist
+ * forgives it with a reason (criterion 2).
+ *
+ * Allowlist entries are stale-checked: an entry that forgives a field that
+ * does not appear anywhere in the JSON output FAILS the test, so the
+ * allowlist shrinks over time.
+ *
+ * DO NOT add allowlist entries without a reason. Headings and invocation-
+ * prefixed hints are the only categories that are structurally OK to forgive;
+ * everything else is a divergence that should be fixed.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../../../..');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a text value for comparison: collapse whitespace, strip the
+ * package-manager invocation prefix, and undo ASCII normalization.
+ * @param {string} s
+ * @returns {string}
+ */
+function normalize(s) {
+ return s
+ .replace(/\s+/g, ' ')
+ .replace(/(npx|pnpm exec|yarn dlx|bunx)\s+astryx/g, 'astryx')
+ .replace(/[\u2014\u2013]/g, '-')
+ .replace(/[\u2018\u2019]/g, "'")
+ .replace(/[\u201C\u201D]/g, '"')
+ .replace(/\u2026/g, '...')
+ .trim();
+}
+
+/**
+ * Extract `key: value` record lines from text output. The formatter always
+ * produces `key: value` (padded) or `key: value`.
+ *
+ * Lines whose key is a known hint prefix (e.g. "Usage:") are excluded —
+ * those are invocation hints allowed by INV4, not data records.
+ * @param {string} text
+ * @returns {Map<string, string[]>}
+ */
+function extractRecordKeys(text) {
+ const HINT_PREFIXES = new Set(['Usage', 'Summary', 'Read', 'Example', 'Tip']);
+ /** @type {Map<string, string[]>} */
+ const map = new Map();
+ for (const line of text.split('\n')) {
+ // Match "word-key: value" but not URLs, headings, or code fences
+ const m = line.match(/^(\w[\w-]*):\s{1,}\S/);
+ if (!m) continue;
+ const key = m[1];
+ if (HINT_PREFIXES.has(key)) continue;
+ const value = line.slice(line.indexOf(':', key.length) + 1).trim();
+ if (!map.has(key)) map.set(key, []);
+ map.get(key).push(normalize(value));
+ }
+ return map;
+}
+
+/**
+ * Extract bulleted list items from text output (`- item`).
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractListItems(text) {
+ return text
+ .split('\n')
+ .filter(line => /^- \S/.test(line))
+ .map(line => normalize(line.slice(2)));
+}
+
+/**
+ * Extract standalone text blocks — lines that are not record lines, list
+ * items, section headings, hint lines, or blank. These correspond to
+ * `text(...)` formatter calls and must carry facts from the JSON.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractTextBlocks(text) {
+ const HINT_PREFIXES = /^(Usage|Summary|Read|Example|Tip|Import from|Related blocks|Each key|Props take|One component|No results|Try a|Browse instead|No failures|All checks|Some checks|Pass --\w)[:.]?/i;
+ const lines = text.split('\n');
+ /** @type {string[]} */
+ const blocks = [];
+ for (let i = 0; i < lines.length; i++) {
+ const trimmed = lines[i].trim();
+ if (!trimmed) continue;
+ // Skip record lines
+ if (/^\w[\w-]*:\s{1,}\S/.test(trimmed)) continue;
+ // Skip list items
+ if (/^- \S/.test(trimmed)) continue;
+ // Skip hints
+ if (HINT_PREFIXES.test(trimmed)) continue;
+ // Skip lines that look like code, commands, or status tokens
+ if (trimmed.startsWith('`') || trimmed.startsWith('$')) continue;
+ if (trimmed.startsWith('[ok]') || trimmed.startsWith('[skip]') ||
+ trimmed.startsWith('[fail]') || trimmed.startsWith('[warn]') ||
+ trimmed.startsWith('!') || trimmed.startsWith('(')) continue;
+ // Skip continuation lines (indented, part of a wrapped record or list)
+ if (/^\s{2,}\S/.test(lines[i])) continue;
+ // Skip section headings: a line preceded by blank (or start) that belongs
+ // to a block followed by blank. Section blocks can be multi-line (heading
+ // + subtitle), so check whether THIS line's block ends before a blank.
+ // Only skip short, heading-like text (no sentence punctuation) to avoid
+ // suppressing real text() facts.
+ const prevBlank = i === 0 || !lines[i - 1]?.trim();
+ const nextBlank = i === lines.length - 1 || !lines[i + 1]?.trim();
+ const looksLikeHeading = trimmed.length <= 80 && !/[.!?]$/.test(trimmed);
+ // Single-line heading: blank before AND after, and heading-like
+ if (prevBlank && nextBlank && looksLikeHeading) continue;
+ // Multi-line heading block: blank before this line, heading-like
+ if (prevBlank && !nextBlank && looksLikeHeading) {
+ let j = i + 1;
+ while (j < lines.length && lines[j]?.trim()) j++;
+ if (j - i <= 3) continue;
+ }
+ // Subtitle line: preceded by a heading-like line preceded by blank
+ if (!prevBlank && nextBlank && i >= 1) {
+ const prevLine = lines[i - 1]?.trim() ?? '';
+ const prevPrevBlank = i < 2 || !lines[i - 2]?.trim();
+ if (prevPrevBlank && prevLine.length <= 80 && !/[.!?]$/.test(prevLine)) continue;
+ }
+ blocks.push(normalize(trimmed));
+ }
+ return blocks;
+}
+
+/**
+ * Collect every leaf string value from JSON data so we can verify text content
+ * appears somewhere in the JSON.
+ * @param {unknown} obj
+ * @returns {Set<string>}
+ */
+function jsonLeafValues(obj) {
+ /** @type {Set<string>} */
+ const values = new Set();
+ if (obj == null) return values;
+ if (typeof obj === 'string') { values.add(normalize(obj)); return values; }
+ if (typeof obj === 'number' || typeof obj === 'boolean') { values.add(String(obj)); return values; }
+ if (Array.isArray(obj)) { for (const item of obj) { for (const v of jsonLeafValues(item)) values.add(v); } return values; }
+ if (typeof obj === 'object') { for (const value of Object.values(obj)) { for (const v of jsonLeafValues(value)) values.add(v); } }
+ return values;
+}
+
+/**
+ * Collect every PRIMITIVE leaf key from a JSON value. Returns keys whose
+ * values are strings, numbers, booleans, or arrays of primitives. Does NOT
+ * return intermediate container keys (objects, arrays of objects).
+ * @param {unknown} obj
+ * @returns {Set<string>}
+ */
+function jsonLeafKeys(obj) {
+ /** @type {Set<string>} */
+ const keys = new Set();
+ if (obj == null || typeof obj !== 'object') return keys;
+ if (Array.isArray(obj)) {
+ for (const item of obj) {
+ if (item != null && typeof item === 'object' && !Array.isArray(item)) {
+ for (const k of jsonLeafKeys(item)) keys.add(k);
+ }
+ }
+ return keys;
+ }
+ for (const [key, value] of Object.entries(obj)) {
+ if (value == null || typeof value !== 'object') {
+ keys.add(key);
+ } else if (Array.isArray(value)) {
+ if (value.length > 0 && typeof value[0] !== 'object') {
+ keys.add(key);
+ } else {
+ for (const item of value) {
+ if (item != null && typeof item === 'object' && !Array.isArray(item)) {
+ for (const k of jsonLeafKeys(item)) keys.add(k);
+ }
+ }
+ }
+ } else {
+ for (const k of jsonLeafKeys(value)) keys.add(k);
+ }
+ }
+ return keys;
+}
+
+/**
+ * Map each leaf key to the set of values it takes across the JSON data.
+ * Used for the JSON→text value-presence check on inline-layout commands.
+ * @param {unknown} obj
+ * @returns {Map<string, Set<string>>}
+ */
+function jsonKeyValues(obj) {
+ /** @type {Map<string, Set<string>>} */
+ const map = new Map();
+ function walk(/** @type {unknown} */ node) {
+ if (node == null || typeof node !== 'object') return;
+ if (Array.isArray(node)) { for (const item of node) walk(item); return; }
+ for (const [key, value] of Object.entries(node)) {
+ if (value == null) continue;
+ if (typeof value !== 'object') {
+ if (!map.has(key)) map.set(key, new Set());
+ map.get(key).add(normalize(String(value)));
+ } else if (Array.isArray(value)) {
+ if (value.length > 0 && typeof value[0] !== 'object') {
+ if (!map.has(key)) map.set(key, new Set());
+ for (const v of value) map.get(key).add(normalize(String(v)));
+ } else {
+ for (const item of value) walk(item);
+ }
+ } else {
+ walk(value);
+ }
+ }
+ }
+ walk(obj);
+ return map;
+}
+
+/**
+ * Check whether a JSON object (at any depth) contains a given key name.
+ * Used for the stale-allowlist check: the field must exist SOMEWHERE in the
+ * full JSON output even if our leaf extractor skips it.
+ * @param {unknown} obj
+ * @param {string} target
+ * @returns {boolean}
+ */
+function jsonContainsKey(obj, target) {
+ if (obj == null || typeof obj !== 'object') return false;
+ if (Array.isArray(obj)) return obj.some(item => jsonContainsKey(item, target));
+ for (const [key, value] of Object.entries(obj)) {
+ if (key === target) return true;
+ if (jsonContainsKey(value, target)) return true;
+ }
+ return false;
+}
+
+// ─── Test cases ─────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} ParityCase
+ * @property {string} name - The manifest command name.
+ * @property {string[]} args - CLI args after `astryx`.
+ * @property {string} [cwd] - Working directory; defaults to REPO_ROOT.
+ * @property {(dir: string) => void} [setup] - Prepare a tmpDir before the run.
+ * @property {string[]} [jsonFieldAllowlist] - JSON keys forgiven from text.
+ * @property {boolean} [skipFieldChecks] - Skip both record-key and field checks.
+ * @property {boolean} [errorExpected] - The command is expected to error.
+ */
+
+/** @type {ParityCase[]} */
+const CASES = [
+ {
+ name: 'blog',
+ args: ['blog'],
+ // Blog fetches the network feed. In CI the feed is unreachable, so
+ // the command errors. The envelope shape is still checked.
+ errorExpected: true,
+ skipFieldChecks: true,
+ },
+ {
+ name: 'build',
+ args: ['build'],
+ // PR #6566 fixes the playbook divergence.
+ skipFieldChecks: true,
+ jsonFieldAllowlist: [
+ 'playbook — PR #6566 adds full playbook fields to the JSON envelope',
+ ],
+ },
+ {
+ name: 'component',
+ args: ['component', '--list'],
+ // #6507 touches this handler; divergences deferred.
+ skipFieldChecks: true,
+ jsonFieldAllowlist: [
+ 'detail — internal detail-level tag, not a user-facing datum',
+ ],
+ },
+ {
+ name: 'discover',
+ args: ['discover'],
+ cwd: '__TMP__',
+ // Empty result (no config). The meta.configured field is projected as
+ // prose in the text.
+ skipFieldChecks: true,
+ jsonFieldAllowlist: [
+ 'configured — expressed as prose "No integrations configured"',
+ ],
+ },
+ {
+ name: 'docs',
+ args: ['docs'],
+ jsonFieldAllowlist: [
+ 'topic — inline layout lead column, not a key: value record',
+ 'description — inline layout trailing column',
+ ],
+ },
+ {
+ name: 'doctor',
+ args: ['doctor'],
+ jsonFieldAllowlist: [
+ 'fix — only present on checks that have a remediation',
+ 'pass — shown in prose "Summary: N passed, ..."',
+ 'warn — shown in prose "Summary: ..., N warnings"',
+ 'fail — shown in prose "Summary: ..., N failures"',
+ 'info — shown in prose "Summary: ..., N info" when nonzero',
+ ],
+ },
+ {
+ name: 'doctor integration validate',
+ args: ['doctor', 'integration', 'validate'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'doctor integration components',
+ args: ['doctor', 'integration', 'components'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'doctor integration docs',
+ args: ['doctor', 'integration', 'docs'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'doctor integration templates',
+ args: ['doctor', 'integration', 'templates'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'gap-report',
+ args: ['gap-report', '--list-categories'],
+ },
+ {
+ name: 'hook',
+ args: ['hook', '--list', '--detail', 'compact'],
+ jsonFieldAllowlist: [
+ 'detail — internal detail-level tag, not a user-facing datum',
+ 'import — shown inside the code() formatted block, not as a record',
+ ],
+ },
+ {
+ name: 'init',
+ args: ['init'],
+ cwd: '__TMP__',
+ // Init emits text via the API logger, not the formatter kit.
+ skipFieldChecks: true,
+ },
+ {
+ name: 'integration add',
+ args: ['integration', 'add', 'component', 'TestComp', '--dry-run'],
+ // Needs a valid integration project to work; errors without one.
+ errorExpected: true,
+ skipFieldChecks: true,
+ },
+ {
+ name: 'integration pack',
+ args: ['integration', 'pack', '--check'],
+ // Needs a packable project; pack itself may exit differently.
+ skipFieldChecks: true,
+ },
+ // ── Layout command: remove these cases when the layout command is deleted ──
+ {
+ name: 'layout check',
+ args: ['layout', 'check', 'Button'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'layout expand',
+ args: ['layout', 'expand', 'Button'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'layout grammar',
+ args: ['layout', 'grammar'],
+ skipFieldChecks: true,
+ },
+ // ── End layout cases ──
+ {
+ name: 'manifest',
+ args: ['manifest'],
+ // Manifest describes the CLI itself; exempt (AST-042 FR1).
+ skipFieldChecks: true,
+ },
+ {
+ name: 'search',
+ args: ['search', 'button'],
+ jsonFieldAllowlist: [
+ 'matchCount — stated in section heading "Results for ... (N)"',
+ 'query — stated in section heading',
+ 'score — only shown with --verbose',
+ 'reason — only shown with --verbose',
+ 'kind — internal domain subtype, not shown in default text',
+ ],
+ },
+ {
+ name: 'swizzle',
+ args: ['swizzle', '--list'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'template',
+ args: ['template', '--list'],
+ // #6265 touches this handler; template id fix deferred.
+ skipFieldChecks: true,
+ jsonFieldAllowlist: [
+ 'id — not shown in text records (#6265)',
+ 'isReady — folded into name as "(WIP)" suffix (#6265)',
+ ],
+ },
+ {
+ name: 'theme add',
+ args: ['theme', 'add', '--list'],
+ // Themes are rendered as list items, not records.
+ skipFieldChecks: true,
+ },
+ {
+ name: 'theme build',
+ args: ['theme', 'build', 'nonexistent.ts'],
+ errorExpected: true,
+ skipFieldChecks: true,
+ },
+ {
+ name: 'theme list',
+ args: ['theme', 'list'],
+ skipFieldChecks: true,
+ },
+ {
+ name: 'theme palette generate',
+ args: ['theme', 'palette', 'generate', 'nonexistent.json'],
+ errorExpected: true,
+ skipFieldChecks: true,
+ },
+ {
+ name: 'theme targets',
+ args: ['theme', 'targets'],
+ jsonFieldAllowlist: [
+ 'filter — null when no filter given; not shown',
+ 'componentCount — shown in section heading subtitle',
+ ],
+ },
+ {
+ name: 'theme template',
+ args: ['theme', 'template'],
+ cwd: '__TMP__',
+ jsonFieldAllowlist: [
+ 'written — stated in status token ([ok] / [skip])',
+ 'path — stated in the "[ok] Wrote ..." line',
+ 'reason — absent; only in skip envelopes',
+ ],
+ },
+ {
+ name: 'upgrade',
+ args: ['upgrade', '--list'],
+ cwd: '__TMP__',
+ },
+];
+
+// ─── Suite ──────────────────────────────────────────────────────────────────
+
+describe('text-json-parity', () => {
+ /** @type {string[]} */
+ let manifestCommands;
+ /** @type {string} */
+ let tmpDir;
+
+ beforeAll(async () => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-parity-'));
+ const {stdout} = await runCli(['manifest', '--json'], {cwd: REPO_ROOT});
+ const manifest = JSON.parse(stdout);
+ manifestCommands = manifest.data.jsonSupported;
+ });
+
+ afterAll(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+ });
+
+ // ── Gate: every JSON-capable command has a parity case ──────────────
+ it('every JSON-capable command in the manifest has a parity case', () => {
+ const covered = new Set(CASES.map(c => c.name));
+ const missing = manifestCommands.filter(cmd => !covered.has(cmd));
+ expect(
+ missing,
+ `Add a parity case for these commands:\n${missing.join('\n')}`,
+ ).toEqual([]);
+ });
+
+ it('every parity case names a real manifest command', () => {
+ const real = new Set(manifestCommands);
+ const stale = CASES.filter(c => !real.has(c.name)).map(c => c.name);
+ expect(stale).toEqual([]);
+ });
+
+ // ── Per-command parity checks ──────────────────────────────────────
+ for (const tc of CASES) {
+ describe(tc.name, () => {
+ /** @type {{text: string, json: any, textStatus: number, jsonStatus: number}} */
+ let run;
+
+ beforeAll(async () => {
+ let cwd = tc.cwd === '__TMP__' ? tmpDir : (tc.cwd || REPO_ROOT);
+ if (tc.cwd === '__TMP__') {
+ const sub = path.join(tmpDir, tc.name.replace(/\s+/g, '-'));
+ fs.mkdirSync(sub, {recursive: true});
+ if (tc.setup) tc.setup(sub);
+ cwd = sub;
+ }
+
+ // Run sequentially: runCli uses process.chdir, which is global
+ // state and races under Promise.all.
+ const textResult = await runCli(tc.args, {cwd});
+ const jsonResult = await runCli([...tc.args, '--json'], {cwd});
+
+ let jsonData;
+ try {
+ jsonData = JSON.parse(jsonResult.stdout);
+ } catch {
+ jsonData = null;
+ }
+
+ run = {
+ text: textResult.stdout,
+ json: jsonData,
+ textStatus: textResult.status,
+ jsonStatus: jsonResult.status,
+ };
+ });
+
+ it('JSON output is a valid envelope', () => {
+ expect(run.json).not.toBeNull();
+ const isSuccess = run.json?.type != null;
+ const isError = run.json?.error != null;
+ expect(isSuccess || isError).toBe(true);
+ });
+
+ it('exit codes match between text and JSON mode', () => {
+ expect(run.textStatus).toBe(run.jsonStatus);
+ });
+
+ if (!tc.skipFieldChecks && !tc.errorExpected) {
+ it('every text record key exists in the JSON data', () => {
+ if (!run.json?.data) return;
+ const textKeys = extractRecordKeys(run.text);
+ const jsonKeys = jsonLeafKeys(run.json.data);
+ if (run.json.meta) {
+ for (const k of jsonLeafKeys(run.json.meta)) jsonKeys.add(k);
+ }
+ const violations = [];
+ for (const key of textKeys.keys()) {
+ if (!jsonKeys.has(key)) {
+ violations.push(key);
+ }
+ }
+ expect(
+ violations,
+ `Text record keys not in JSON:\n${violations.join(', ')}`,
+ ).toEqual([]);
+ });
+
+ it('every JSON leaf field appears in the text or is allowlisted', () => {
+ if (!run.json?.data) return;
+ const textKeys = extractRecordKeys(run.text);
+ const jsonKeys = jsonLeafKeys(run.json.data);
+ const keyVals = jsonKeyValues(run.json.data);
+ const allowedKeys = new Set(
+ (tc.jsonFieldAllowlist || []).map(e => e.split(' — ')[0].trim()),
+ );
+
+ const missing = [];
+ for (const key of jsonKeys) {
+ const inRecords = textKeys.has(key);
+ // Check for `key:` as a field label at start of line.
+ const asLabel = new RegExp(`(?:^|\\n)\\s*${key}:`, 'm').test(run.text);
+ // For inline records (no labels): check if THIS KEY's values
+ // appear in the text. This catches inline-layout projections
+ // where the key name is only in the section subtitle.
+ const myVals = keyVals.get(key) ?? new Set();
+ const valuesInText = !inRecords && !asLabel && [...myVals].some(v =>
+ v.length > 2 && run.text.includes(v),
+ );
+ const allowed = allowedKeys.has(key);
+ if (!inRecords && !asLabel && !valuesInText && !allowed) {
+ missing.push(key);
+ }
+ }
+ expect(
+ missing,
+ `JSON fields not in text and not allowlisted:\n${missing.join(', ')}`,
+ ).toEqual([]);
+ });
+
+ it('text list items and block content appear in JSON data', () => {
+ if (!run.json?.data) return;
+ const jsonValues = jsonLeafValues(run.json.data);
+ if (run.json.meta) {
+ for (const v of jsonLeafValues(run.json.meta)) jsonValues.add(v);
+ }
+ const items = extractListItems(run.text);
+ const textBlocks = extractTextBlocks(run.text);
+ const violations = [];
+ for (const item of items) {
+ // Each list item should match (or be a substring of) some JSON value.
+ const found = [...jsonValues].some(
+ jv => jv === item || jv.includes(item) || item.includes(jv),
+ );
+ if (!found) {
+ violations.push(`[list] ${item.slice(0, 80)}`);
+ }
+ }
+ for (const block of textBlocks) {
+ // Each text block should contain at least one word that appears in
+ // the JSON values. A block with no JSON overlap is a fact the
+ // envelope does not carry. Numbers (even short) count because
+ // they are data.
+ const words = block.split(/\s+/).filter(w =>
+ w.length > 3 || /^\d+$/.test(w),
+ );
+ const anyOverlap = words.some(w =>
+ [...jsonValues].some(jv => jv.includes(w)),
+ );
+ if (!anyOverlap && words.length > 0) {
+ violations.push(`[text] ${block.slice(0, 80)}`);
+ }
+ }
+ expect(
+ violations,
+ `Text content not found in JSON data:\n${violations.join('\n')}`,
+ ).toEqual([]);
+ });
+ }
+
+ // Stale allowlist check
+ if (tc.jsonFieldAllowlist && tc.jsonFieldAllowlist.length > 0) {
+ it('allowlist entries are not stale', () => {
+ if (!run.json) return;
+ const searchTarget = run.json.data ?? run.json;
+ const stale = [];
+ for (const entry of tc.jsonFieldAllowlist) {
+ const key = entry.split(' — ')[0].trim();
+ if (!jsonContainsKey(searchTarget, key) && !jsonContainsKey(run.json.meta, key)) {
+ stale.push(entry);
+ }
+ }
+ expect(
+ stale,
+ `Stale allowlist entries — remove them:\n${stale.join('\n')}`,
+ ).toEqual([]);
+ });
+ }
+ });
+ }
+
+ // ── Upgrade failure-path regression tests ────────────────────────
+ // The upgrade handler silences the logger for --list and replays the error
+ // in the catch. These tests prove both list and non-list failures print
+ // the error exactly once and exit 1, in both text and --json mode.
+ describe('upgrade failure paths', () => {
+ it('upgrade --list --registry prints error once on stderr and exits 1 (text)', async () => {
+ const sub = path.join(tmpDir, 'upgrade-list-fail');
+ fs.mkdirSync(sub, {recursive: true});
+ const r = await runCli(['upgrade', '--list', '--registry'], {cwd: sub});
+ expect(r.status).toBe(1);
+ // The error message should appear exactly once across stdout+stderr.
+ const combined = r.stdout + r.stderr;
+ const occurrences = combined.split('cannot be used together').length - 1;
+ expect(occurrences, 'error should appear exactly once').toBe(1);
+ });
+
+ it('upgrade --list --registry emits one error envelope in --json mode', async () => {
+ const sub = path.join(tmpDir, 'upgrade-list-fail-json');
+ fs.mkdirSync(sub, {recursive: true});
+ const r = await runCli(['upgrade', '--list', '--registry', '--json'], {cwd: sub});
+ expect(r.status).toBe(1);
+ const parsed = JSON.parse(r.stdout);
+ expect(parsed).toHaveProperty('error');
+ expect(parsed).not.toHaveProperty('type');
+ });
+
+ it('non-list upgrade failure prints error once on stderr and exits 1 (text)', async () => {
+ const sub = path.join(tmpDir, 'upgrade-nonlist-fail');
+ fs.mkdirSync(sub, {recursive: true});
+ const r = await runCli(['upgrade', '--from', 'notsemver'], {cwd: sub});
+ expect(r.status).toBe(1);
+ // The error should appear exactly once.
+ const combined = r.stdout + r.stderr;
+ const lines = combined.split('\n').filter(l => l.includes('notsemver') || l.includes('ERR'));
+ // At most one line carries the error; zero is OK if the API formats
+ // differently, but more than one means duplication.
+ expect(lines.length, 'error should not be duplicated').toBeLessThanOrEqual(1);
+ });
+
+ it('non-list upgrade failure emits one error envelope in --json mode', async () => {
+ const sub = path.join(tmpDir, 'upgrade-nonlist-fail-json');
+ fs.mkdirSync(sub, {recursive: true});
+ const r = await runCli(['upgrade', '--from', 'notsemver', '--json'], {cwd: sub});
+ expect(r.status).toBe(1);
+ const parsed = JSON.parse(r.stdout);
+ expect(parsed).toHaveProperty('error');
+ });
+ });
+});
diff --git a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs
index d10d813822..b650224e6d 100644
--- a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs
+++ b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs
@@ -17,8 +17,9 @@ describe('astryx theme targets', () => {
const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);
expect(status).toBe(0);
- expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);
- expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);
+ // Inline layout: key component - props - states - className
+ expect(stdout).toMatch(/^switch\s+Switch - size - checked, disabled - astryx-switch$/m);
+ expect(stdout).toMatch(/^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m);
expect(stdout).toMatch(/4 across 1 component/);
});
@@ -28,7 +29,7 @@ describe('astryx theme targets', () => {
expect(status).toBe(0);
expect(stdout).toMatch(/^popover\s{2,}Popover/m);
expect(stdout).toMatch(
- /^popover-surface \[deprecated; use popover\]\s{2,}Popover/m,
+ /^popover-surface\s{2,}Popover - astryx-popover-surface - deprecated; use popover$/m,
);
});
diff --git a/packages/cli/clients/cli/commands/upgrade.mjs b/packages/cli/clients/cli/commands/upgrade.mjs
index 1eb53376a7..2e2ea0092f 100644
--- a/packages/cli/clients/cli/commands/upgrade.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.mjs
@@ -13,6 +13,7 @@
*/
import {jsonOut, jsonError} from '../../../foundation/response/json.mjs';
+import {emit, section, records} from '../formatters/index.mjs';
import {logger} from '../../../api/logger.mjs';
import {AstryxError} from '../../../api/error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
@@ -33,27 +34,45 @@ export function registerUpgrade(program) {
*/
async options => {
const json = program.opts().json || false;
- logger.setSilent(json);
+ const isList = Boolean(options.list);
+ // Silence the logger for --list so the handler renders from the
+ // result (parity with --json), and for --json as before.
+ // Re-enable on error so handled failures still print.
+ logger.setSilent(json || isList);
/** @type {import('../../../api/upgrade/upgrade.type.mjs').UpgradeListResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRegistryResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeStatusResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRunResponse} */
let result;
try {
result = await upgradeApi(options, {cwd: process.cwd()});
} catch (e) {
- // Handled failures throw AstryxError: --json emits the structured
- // envelope (byte-identical to the old inline jsonError) + exits 1;
- // human mode already saw the error line + outro via the logger, so we
- // just set the exit code. Anything else is unexpected — let the
- // top-level boundary in bin/astryx.mjs format it as before.
+ // Re-enable the logger so the error is visible in text mode.
+ // For --list the logger was silent; for other modes the API
+ // already printed the error before throwing.
+ logger.setSilent(json);
if (e instanceof AstryxError) {
if (json) jsonError(e.message, undefined, e.code);
- else process.exitCode = 1;
+ else {
+ // The logger was silent only for --list; replay the error there.
+ // Non-list failures were already printed by the API.
+ if (isList) logger.error(e.message);
+ process.exitCode = 1;
+ }
return NO_RESULT_SET;
}
throw e;
}
if (json) jsonOut(result);
+ else if (result.type === 'upgrade.list') {
+ // Render the list from the result, not the API logger, so the text
+ // carries the same fields the JSON does (name, title, version, optional).
+ emit(
+ section('Available codemods'),
+ records(result.data, {
+ fields: ['name', 'title', 'version', 'optional'],
+ }),
+ );
+ }
const registrySummary =
result.type === 'upgrade.registry'
diff --git a/packages/cli/clients/cli/formatters/index.mjs b/packages/cli/clients/cli/formatters/index.mjs
index a867c2f5b0..161e62a731 100644
--- a/packages/cli/clients/cli/formatters/index.mjs
+++ b/packages/cli/clients/cli/formatters/index.mjs
@@ -152,6 +152,8 @@ function toAscii(s) {
.replace(/[\u2018\u2019]/g, "'")
.replace(/[\u201C\u201D]/g, '"')
.replace(/\u2026/g, '...')
+ .replace(/\u2192/g, '->')
+ .replace(/\u2190/g, '<-')
.replace(/\u00a0/g, ' ');
}
diff --git a/packages/cli/clients/cli/formatters/index.test.mjs b/packages/cli/clients/cli/formatters/index.test.mjs
index 15af2d58db..57b43c8c02 100644
--- a/packages/cli/clients/cli/formatters/index.test.mjs
+++ b/packages/cli/clients/cli/formatters/index.test.mjs
@@ -117,6 +117,12 @@ describe('ASCII normalization', () => {
expect(list(['Avatar \u2014 Group']).toString()).toBe('- Avatar - Group');
});
+ it('converts Unicode arrows to ASCII arrows', () => {
+ expect(text('Rename items \u2192 options').toString()).toBe('Rename items -> options');
+ expect(text('options \u2190 items').toString()).toBe('options <- items');
+ expect(record({title: 'a \u2192 b'}).toString()).toBe('title: a -> b');
+ });
+
it('leaves code verbatim (no normalization)', () => {
expect(code('a \u2014 b').toString()).toBe('a \u2014 b');
});