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

package/clients/cli/commands/upgrade.flag-help.test.mjs

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` documents how its flags interact and when it exits 1,
+ * and behaves as documented. Option text is read from the generated manifest
+ * (the same strings `--help` prints); exit codes from the CommandDoc.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as upgradeDoc} from './upgrade.doc.mjs';
+
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-flags-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+  fs.mkdirSync(path.join(tmpDir, 'src'));
+  fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const foo = 1;\n');
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} name @param {string} version */
+function installPackage(name, version) {
+  const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name, version}));
+}
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  fs.mkdirSync(path.dirname(path.join(tmpDir, rel)), {recursive: true});
+  fs.writeFileSync(path.join(tmpDir, rel), body);
+}
+
+/**
+ * upgrade's option descriptions from the manifest, keyed by long flag.
+ * @returns {Promise<Record<string, string>>}
+ */
+async function upgradeOptions() {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  const upgrade = JSON.parse(stdout).data.commands.find(
+    (/** @type {{name: string}} */ c) => c.name === 'upgrade',
+  );
+  return Object.fromEntries(
+    upgrade.options.map((/** @type {{flag: string, description: string}} */ o) => [
+      o.flag.match(/--[a-z-]+/)?.[0],
+      o.description,
+    ]),
+  );
+}
+
+/** @param {string[]} args */
+async function upgradeJson(args) {
+  const result = await runCli(['--json', 'upgrade', ...args], tmpDir);
+  return {status: result.status, envelope: JSON.parse(result.stdout)};
+}
+
+const exit1 = () => upgradeDoc.exitCodes?.find(e => e.code === 1)?.when ?? '';
+
+const MIGRATION_FLAGS = [
+  ['--from', '0.5.0'],
+  ['--force'],
+  ['--codemod', 'x'],
+  ['--skip-codemod', 'x'],
+  ['--integration', 'x'],
+  ['--install-deps'],
+];
+
+describe('astryx upgrade flag interactions', () => {
+  it('--list: help says it ignores every other flag but --registry, and it does', async () => {
+    const options = await upgradeOptions();
+    expect(options['--list']).toMatch(/Every other flag is ignored, except --registry/);
+
+    installPackage('@astryxdesign/core', '0.6.0');
+    const listed = await upgradeJson([
+      '--list',
+      '--from',
+      'bogus',
+      '--codemod',
+      'bogus',
+      '--apply',
+      '--path',
+      '../outside',
+    ]);
+    expect(listed.status).toBe(0);
+    expect(listed.envelope.type).toBe('upgrade.list');
+
+    const refused = await upgradeJson(['--list', '--registry']);
+    expect(refused.status).toBe(1);
+    expect(refused.envelope.code).toBe('ERR_INVALID_ARGUMENT');
+  }, SLOW);
+
+  it('--registry: help names every flag it refuses, and each exits 1', async () => {
+    const options = await upgradeOptions();
+    for (const [flag] of MIGRATION_FLAGS) expect(options['--registry']).toContain(flag);
+    expect(options['--registry']).toContain('--list');
+    expect(options['--registry']).toContain('ERR_INVALID_ARGUMENT');
+
+    for (const flag of MIGRATION_FLAGS) {
+      const {status, envelope} = await upgradeJson(['--registry', ...flag]);
+      expect(status, flag[0]).toBe(1);
+      expect(envelope.code, flag[0]).toBe('ERR_INVALID_ARGUMENT');
+    }
+  }, SLOW);
+
+  it('--codemod: help says it runs optional codemods and skips the composition check, and it does', async () => {
+    const options = await upgradeOptions();
+    expect(options['--codemod']).toMatch(/Optional codemods run only when named here/);
+    expect(options['--codemod']).toMatch(/skips the check of ShadCN-copied compositions/);
+
+    installPackage('@astryxdesign/core', '0.0.15');
+    // An unreadable receipt leaves a registry item unresolved.
+    write('src/components/.astryx/broken.json', '{}');
+
+    const normal = await upgradeJson(['--from', '0.0.14']);
+    expect(normal.status).toBe(1);
+    expect(normal.envelope.data.registryCompositions.invalid).toBe(1);
+
+    // 0.0.15 ships one optional codemod, which only runs when named.
+    const named = await upgradeJson(['--from', '0.0.14', '--codemod', 'migrate-theme-selectors-to-data-attrs']);
+    expect(named.status).toBe(0);
+    expect(named.envelope.data.codemods).toBe(1);
+    expect(named.envelope.data.registryCompositions).toBeUndefined();
+    expect(normal.envelope.data.codemods).toBe(6);
+  }, SLOW);
+
+  it('--from: help names the legacy @xds/core target, which upgrade falls back to', async () => {
+    const options = await upgradeOptions();
+    expect(options['--from']).toMatch(/legacy @xds\/core/);
+
+    installPackage('@xds/core', '0.0.20');
+    const {status, envelope} = await upgradeJson(['--from', '0.0.19']);
+    expect(status).toBe(0);
+    expect(envelope.data.to).toBe('0.0.20');
+  }, SLOW);
+});
+
+describe('astryx upgrade exit codes', () => {
+  it('lists a missing core, which exits 1 in both modes', async () => {
+    expect(exit1()).toMatch(/no installed @astryxdesign\/core/);
+    const text = await runCli(['upgrade', '--from', '0.5.0'], tmpDir);
+    const json = await upgradeJson(['--from', '0.5.0']);
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+    expect(json.envelope.code).toBe('ERR_VERSION_DETECT');
+  }, SLOW);
+
+  it('lists an astryx.config no codemod repairs, which exits 1', async () => {
+    expect(exit1()).toMatch(/astryx\.config that fails validation/);
+    installPackage('@astryxdesign/core', '0.6.0');
+    write('astryx.config.mjs', "export default {theme: 'neutral'};\n");
+    const {status, envelope} = await upgradeJson(['--from', '0.5.0']);
+    expect(status).toBe(1);
+    expect(envelope.code).toBe('ERR_INVALID_ARGUMENT');
+  }, SLOW);
+
+  it('lists a post-codemod hook failure, which exits 1', async () => {
+    expect(exit1()).toMatch(/post-codemod hook failure/);
+    installPackage('@astryxdesign/core', '0.6.0');
+    write(
+      'src/panel.tsx',
+      "import {useResizable} from '@astryxdesign/core';\nexport const r = () => useResizable({minSizePx: 200});\n",
+    );
+    write(
+      'astryx.config.mjs',
+      "export default {hooks: {postCodemod: [{buildCommand: () => { throw new Error('formatter crashed'); }}]}};\n",
+    );
+    const {status, envelope} = await upgradeJson(['--from', '0.5.0']);
+    expect(status).toBe(1);
+    expect(envelope.code).toBe('ERR_CODEMOD_FAILED');
+    expect(envelope.error).toMatch(/Post-codemod hook failed/);
+  }, SLOW);
+
+  it('lists a missing jscodeshift and the refused flag combinations', () => {
+    expect(exit1()).toMatch(/jscodeshift missing and not installed/);
+    expect(exit1()).toMatch(/--registry with --list or a migration flag/);
+  });
+});

package/clients/cli/commands/upgrade.hook-output.test.mjs

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Subprocess test: a post-codemod hook that prints must not corrupt the
+ * `upgrade --json` envelope. Stdout carries exactly one envelope; the hook's
+ * output goes to stderr.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
+
+let tmpDir;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/** @param {string[]} args */
+function runCli(args) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd: tmpDir,
+    encoding: 'utf8',
+    timeout: 60_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {...process.env, FORCE_COLOR: '0', CI: ''},
+  });
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-hook-output-'));
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+  );
+  write(
+    'src/panel.tsx',
+    "import {useResizable} from '@astryxdesign/core';\n" +
+      'export const usePanel = () => useResizable({defaultSize: 250, minSizePx: 200});\n',
+  );
+  write(
+    'astryx.config.mjs',
+    'export default {hooks: {postCodemod: [{name: "noisy", buildCommand: ({files}) => {\n' +
+      '  console.log("hook saw " + files.join(","));\n' +
+      '  process.stdout.write("hook raw write\\n");\n' +
+      '  return null;\n' +
+      '}}]}};\n',
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('upgrade post-codemod hook output', () => {
+  it('keeps --json stdout to one envelope and sends hook output to stderr', () => {
+    const r = runCli([
+      '--json',
+      'upgrade',
+      '--from',
+      '0.5.0',
+      '--codemod',
+      'rename-resizable-pixel-bounds',
+      '--apply',
+    ]);
+
+    expect(r.signal).toBeNull();
+    expect(r.status).toBe(0);
+    const envelope = JSON.parse(r.stdout);
+    expect(envelope.type).toBe('upgrade.run');
+    expect(envelope.data.filesChanged).toBe(1);
+    expect(r.stderr).toContain('hook saw src/panel.tsx');
+    expect(r.stderr).toContain('hook raw write');
+    expect(fs.readFileSync(path.join(tmpDir, 'src/panel.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+  });
+});

package/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'
@@ -65,6 +84,9 @@ export function registerUpgrade(program) {
                 ? result.data.registryCompositions
                 : undefined;
         if (registrySummary && !registrySummary.ok) process.exitCode = 1;
+        if (result.type === 'upgrade.run' && result.data.complete === false) {
+          process.exitCode = 1;
+        }
 
         // `--list` is the one lookup here: which migrations exist for the
         // range. Everything else migrates the project — an effect, reported by

package/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, ' ');
 }
 

package/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');
   });

package/clients/cli/index.mjs

@@ -16,7 +16,6 @@ import {Command, Option} from 'commander';
 import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {checkForUpdate} from './lib/update-check.mjs';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';
 import {buildManifest} from './lib/manifest.mjs';
@@ -25,7 +24,8 @@ 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';
-import {markReportsResult} from './lib/define-command.mjs';
+import {addExitCodesHelp, markReportsResult} from './lib/define-command.mjs';
+import {doc as manifestDoc} from './commands/manifest.doc.mjs';
 import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
 
@@ -275,8 +275,13 @@ const commands = [
   {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
 ];
 
-const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+/** An integration package's manifest: the package is not an app to set up. */
+const INTEGRATION_MANIFEST_FILES = [
+  'astryx.integration.ts',
+  'astryx.integration.mjs',
+  'astryx.integration.js',
+];
 
 /**
  * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
@@ -352,7 +357,7 @@ export async function createProgram() {
     )
     .option(
       '--json',
-      'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
+      'Output as typed JSON. Success envelope: { apiVersion, type, data, meta? }. Error envelope: { apiVersion, error, code, suggestions? }.',
     )
     .addHelpCommand('help', 'Show all commands')
     .action((options, cmd) => {
@@ -499,25 +504,6 @@ export async function createProgram() {
     process.exit(1);
   });
 
-  /**
-   * Post-action hook: print update hint after any command output.
-   * Only fires for commands that produce output agents read (component, docs, etc.).
-   * Suppressed when --json is active to avoid contaminating stdout.
-   */
-  program.hook('postAction', (thisCommand, actionCommand) => {
-    if (program.opts().json) return;
-    try {
-      if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
-        const hint = checkForUpdate();
-        if (hint) {
-          console.error(`\n${hint}`);
-        }
-      }
-    } catch {
-      // Never let update check break the CLI
-    }
-  });
-
   /**
    * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
    * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
@@ -539,6 +525,8 @@ export async function createProgram() {
       if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
       const cwd = process.cwd();
       if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+      // An integration package is not an app: `init` is not its next step.
+      if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
       // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
       // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
@@ -557,16 +545,18 @@ export async function createProgram() {
       mod[cmd.register](program);
     } catch (e) {
       // Command fails to load but CLI still works
+      const reason = /** @type {any} */ (e).message;
       const stub = program
         .command(cmd.name)
-        .description(`(failed to load: ${/** @type {any} */ (e).message})`)
+        .description(`(failed to load: ${reason})`)
         .action(() => {
           // Nothing loaded, so nothing was answered — say that rather than
           // leaving the run's result unreported.
           debug.recordCommandResult(debug.NO_RESULT_SET);
-          console.error(`Command "${cmd.name}" failed to load:`);
-          console.error(/** @type {any} */ (e).message);
-          process.exit(1);
+          // cliError, so --json still gets its one envelope.
+          cliError(`Command "${cmd.name}" failed to load: ${reason}`, {
+            code: ERROR_CODES.ERR_UNKNOWN,
+          });
         });
       markReportsResult(stub);
     }
@@ -601,20 +591,21 @@ export async function createProgram() {
       }
       // Human-readable summary as greppable records (agents should use --json).
       // One record per command: name, whether it supports --json, and the
-      // description.
+      // description. Field names are the manifest entry's own keys.
       emit(
         section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
         records(
           manifest.commands.map(c => ({
-            command: c.name,
+            name: c.name,
             json: c.json ? 'yes' : '',
             description: c.description || '',
           })),
-          {fields: ['command', 'json', 'description']},
+          {fields: ['name', 'json', 'description']},
         ),
         text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
       );
     });
+  addExitCodesHelp(manifestCommand, manifestDoc.exitCodes);
   markReportsResult(manifestCommand);
 
   // Hidden command used by package.json postinstall scripts

package/clients/cli/latest-version-env.test.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ASTRYX_LATEST_VERSION is not a CLI control: setting it changes nothing
+ * a command prints. It used to append an update hint to `component` and
+ * `docs`.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const VARIABLE = 'ASTRYX_LATEST_VERSION';
+
+/** @type {string} */
+let dir;
+/** @type {string | undefined} */
+let saved;
+
+beforeEach(() => {
+  saved = process.env[VARIABLE];
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-latest-version-'));
+  // A project on an old core, so a "newer version" hint would have a reason to fire.
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'app', private: true, dependencies: {'@astryxdesign/core': '^0.0.1'}}),
+  );
+});
+
+afterEach(() => {
+  if (saved === undefined) delete process.env[VARIABLE];
+  else process.env[VARIABLE] = saved;
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+describe('ASTRYX_LATEST_VERSION', () => {
+  it('does not change what astryx docs prints', async () => {
+    delete process.env[VARIABLE];
+    const without = await runCli(['docs'], {cwd: dir});
+    process.env[VARIABLE] = '999.0.0';
+    const withVariable = await runCli(['docs'], {cwd: dir});
+
+    expect(withVariable.status).toBe(without.status);
+    expect(withVariable.stdout).toBe(without.stdout);
+    expect(withVariable.stderr).toBe(without.stderr);
+    expect(withVariable.stderr).not.toMatch(/newer version/i);
+  });
+});

package/clients/cli/lib/cli-error.test.mjs

@@ -133,6 +133,13 @@ describe('cliError — JSON mode', () => {
     expect(env.suggestions).toEqual([{name: 'Button', reason: 'closest match'}]);
   });
 
+  it('replaces an unregistered code with ERR_UNKNOWN', () => {
+    expect(() =>
+      cliError('EACCES: permission denied', {code: 'EACCES'}),
+    ).toThrow('__exit_1__');
+    expect(JSON.parse(stdout[0]).code).toBe('ERR_UNKNOWN');
+  });
+
   it('always exits 1 in JSON mode (custom exitCode is ignored — contract)', () => {
     expect(() => cliError('msg', {exitCode: 2})).toThrow('__exit_1__');
     expect(exitCode).toBe(1);

package/clients/cli/lib/component-format.mjs

@@ -71,7 +71,7 @@ function formatPropsTable(props) {
   lines.push('| Prop | Type | Default | Description |');
   lines.push('|------|------|---------|-------------|');
   for (const p of props) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '—';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
     lines.push(
       `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
@@ -190,11 +190,11 @@ function formatTargetsTable(docs, themeData) {
       ...themeVariants.map((/** @type {string} */ v) => `${v}*`),
     ];
 
-    const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '—';
-    const statesStr = states.length > 0 ? states.join(', ') : '—';
+    const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '-';
+    const statesStr = states.length > 0 ? states.join(', ') : '-';
     const dataAttrs = getTargetDataAttributes(target);
     const dataAttrsStr =
-      dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '—';
+      dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '-';
 
     const className = target.deprecatedFor
       ? `\`${target.className}\` _(deprecated; use \`${target.deprecatedFor}\`)_`
@@ -342,7 +342,7 @@ export function formatFull(docs, options = {}) {
       const publicVars = docs.theming.vars.filter((/** @type {any} */ v) => !v.private && !v.derived);
 
       if (publicVars.length > 0) {
-        sections.push('**Themeable CSS variables** — additional properties that can be overridden in `defineTheme` component overrides.\n');
+        sections.push('**Themeable CSS variables** - additional properties that can be overridden in `defineTheme` component overrides.\n');
         const varLines = [];
         varLines.push('| CSS Variable | Default | Description |');
         varLines.push('|-------------|---------|-------------|');
@@ -544,7 +544,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
     signatureProps.length > 0
       ? `${displayName}(${signatureProps.join(', ')})`
       : displayName;
-  output.push(importHint ? `${sigStr}  ← from '${importHint}'` : sigStr);
+  output.push(importHint ? `${sigStr}  <- from '${importHint}'` : sigStr);
 
   // Description (shortened)
   if (description) {
@@ -569,7 +569,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   // Derived properties (if any)
   if (docs.theming?.derived?.length) {
     const derivedNames = docs.theming.derived
-      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} → container tokens` : `${d.property} → ${(d.vars || []).join(', ')}`)
+      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} -> container tokens` : `${d.property} -> ${(d.vars || []).join(', ')}`)
       .join('; ');
     output.push(`  Derived: ${derivedNames}`);
   }
@@ -579,7 +579,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
     const { themeData = null } = options;
     const targetParts = docs.theming.targets.map((/** @type {any} */ t) => {
       const parts = [t.className];
-      if (t.deprecatedFor) parts.push(`deprecated→${t.deprecatedFor}`);
+      if (t.deprecatedFor) parts.push(`deprecated->${t.deprecatedFor}`);
       const dataAttrs = getTargetDataAttributes(t);
       if (dataAttrs.length) parts.push(`preferred attrs: ${dataAttrs.join(', ')}`);
       if (t.visualProps?.length) parts.push(`variants: ${t.visualProps.join(', ')}`);
@@ -595,7 +595,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
 
   // Other props
   if (otherProps.length > 0) {
-    output.push(`  ${otherProps.join(' · ')}`);
+    output.push(`  ${otherProps.join(', ')}`);
   }
 
   // First code example

package/clients/cli/lib/component-format.test.mjs

@@ -157,7 +157,7 @@ describe('deprecated theming target guidance', () => {
 
   it('keeps the replacement in brief agent guidance', () => {
     expect(formatBrief(docs, 'Example')).toContain(
-      'astryx-old-target deprecated→new-target',
+      'astryx-old-target deprecated->new-target',
     );
   });
 });