@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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

@@ -11,7 +11,8 @@
  * which fields to show and in what order.
  *
  * Constraints (deliberately narrow):
- *   - Plain ASCII only. No color, no TTY detection, no width wrapping. Output is
+ *   - Plain ASCII only. No color and no TTY detection. Long lines wrap at a
+ *     fixed {@link WRAP_WIDTH}, never at the terminal's width, so 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')`).
@@ -33,6 +34,50 @@ export const BULLET = '-';
 export const ERR = '!!';
 export const WARN = '!';
 
+/** The column long human-output lines wrap at. */
+export const WRAP_WIDTH = 120;
+
+/** The widest first column an inline record pads to; a longer value overhangs. */
+const INLINE_LEAD_MAX = 32;
+
+/**
+ * Characters a terminal draws two columns wide: CJK ideographs and
+ * punctuation, kana, hangul, and fullwidth forms. A line may break between
+ * any two of them.
+ */
+const WIDE_CHAR =
+  /[\u1100-\u115f\u2e80-\u303e\u3041-\u33ff\u3400-\u4dbf\u4e00-\u9fff\ua000-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/u;
+
+/**
+ * How many terminal columns a string takes.
+ * @param {string} s
+ * @returns {number}
+ */
+export function displayWidth(s) {
+  let width = 0;
+  for (const ch of String(s)) width += WIDE_CHAR.test(ch) ? 2 : 1;
+  return width;
+}
+
+/**
+ * Cut a line to `width` columns, ending it with `...` when anything was cut.
+ * @param {string} line
+ * @param {number} width
+ * @returns {string}
+ */
+function truncateToWidth(line, width) {
+  if (displayWidth(line) <= width) return line;
+  let out = '';
+  let used = 0;
+  for (const ch of line) {
+    const w = WIDE_CHAR.test(ch) ? 2 : 1;
+    if (used + w > width - 3) break;
+    out += ch;
+    used += w;
+  }
+  return `${out.trimEnd()}...`;
+}
+
 /**
  * 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
@@ -67,6 +112,13 @@ export class Block {
  * @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).
+ * @property {'stacked' | 'inline'} [layout] - `stacked` (the default): one
+ *   `key: value` line per field, a blank line between records. `inline`: one
+ *   record per line, the first field in a padded column and the rest joined by
+ *   ` - `, for a list a reader scans.
+ * @property {'wrap' | 'truncate'} [overflow] - What an inline record longer
+ *   than {@link WRAP_WIDTH} does: `wrap` (the default) continues under the
+ *   first column; `truncate` cuts it to one line.
  */
 
 /** @param {unknown} v @returns {boolean} */
@@ -100,9 +152,77 @@ function toAscii(s) {
     .replace(/[\u2018\u2019]/g, "'")
     .replace(/[\u201C\u201D]/g, '"')
     .replace(/\u2026/g, '...')
+    .replace(/\u2192/g, '->')
+    .replace(/\u2190/g, '<-')
     .replace(/\u00a0/g, ' ');
 }
 
+/**
+ * Word-wrap text at `width`, keeping its own line breaks. A word longer than
+ * the width stays whole on a line of its own. Continuation lines start with
+ * `indent`.
+ * @param {string} input
+ * @param {{width?: number, indent?: string}} [options]
+ * @returns {string}
+ */
+export function wrapText(input, {width = WRAP_WIDTH, indent = ''} = {}) {
+  return String(input)
+    .split('\n')
+    .map(line => wrapLine(line, width, indent))
+    .join('\n');
+}
+
+/**
+ * @param {string} line
+ * @param {number} width
+ * @param {string} indent
+ * @returns {string}
+ */
+function wrapLine(line, width, indent) {
+  if (displayWidth(line) <= width) return line;
+  const lead = /^\s*/.exec(line)?.[0] ?? '';
+  // Tokens a line may break between: words, and each wide character on its
+  // own, since CJK text has no spaces to break at. `gap` is what joined a
+  // token to the one before it.
+  /** @type {{text: string, gap: string}[]} */
+  const tokens = [];
+  let gap = '';
+  let word = '';
+  const flush = () => {
+    if (word === '') return;
+    tokens.push({text: word, gap});
+    gap = '';
+    word = '';
+  };
+  for (const ch of line.slice(lead.length)) {
+    if (ch === ' ') {
+      flush();
+      gap = ' ';
+    } else if (WIDE_CHAR.test(ch)) {
+      flush();
+      tokens.push({text: ch, gap});
+      gap = '';
+    } else {
+      word += ch;
+    }
+  }
+  flush();
+  /** @type {string[]} */
+  const out = [];
+  let current = lead;
+  tokens.forEach(({text: token, gap: before}, i) => {
+    const joined = i === 0 ? current + token : current + before + token;
+    if (i > 0 && displayWidth(joined) > width && current.trim() !== '') {
+      out.push(current);
+      current = indent + token;
+    } else {
+      current = joined;
+    }
+  });
+  out.push(current);
+  return out.join('\n');
+}
+
 /**
  * A group label, optionally with an explanatory subtitle rendered on the line(s)
  * directly beneath the heading (no blank line between). Whatever list/records
@@ -177,10 +297,53 @@ export function record(obj, options = {}) {
  * @returns {Block}
  */
 export function records(items, options = {}) {
+  if (options.layout === 'inline') return inlineRecords(items, options);
   const blocks = items.map(o => record(o, options).toString()).filter(Boolean);
   return new Block(blocks.join('\n\n'));
 }
 
+/**
+ * @param {any[]} items
+ * @param {RecordOptions} options
+ * @returns {Block}
+ */
+function inlineRecords(items, options) {
+  const [lead, ...rest] = (options.fields ?? Object.keys(items[0] ?? {})).filter(
+    k => !options.omit?.includes(k),
+  );
+  if (lead == null) return new Block('');
+  /** @param {any} o @param {string} k */
+  const value = (o, k) => {
+    const fmt = options.format?.[k];
+    return fmt ? fmt(o[k]) : renderValue(o[k]);
+  };
+  const leads = items.map(o => (isEmpty(o[lead]) ? '' : value(o, lead)));
+  const column = Math.min(
+    Math.max(0, ...leads.map(l => displayWidth(l))),
+    INLINE_LEAD_MAX,
+  );
+  const indent = ' '.repeat(column + 2);
+  const lines = items.map((o, i) => {
+    const tail = toAscii(
+      rest
+        .filter(k => !isEmpty(o[k]))
+        .map(k => value(o, k))
+        .join(' - '),
+    );
+    if (tail === '') return toAscii(leads[i]);
+    const head = toAscii(`${leads[i].padEnd(column)}  `);
+    if (options.overflow === 'truncate') {
+      return truncateToWidth(head + tail, WRAP_WIDTH);
+    }
+    // Wrap only the tail, so the padded first column survives the wrap.
+    const [first, ...more] = wrapText(tail, {
+      width: Math.max(20, WRAP_WIDTH - displayWidth(head)),
+    }).split('\n');
+    return [head + first, ...more.map(line => indent + line)].join('\n');
+  });
+  return new Block(lines.join('\n'));
+}
+
 /**
  * A verbatim block — source dumps, layout skeletons, or a markdown doc. Output
  * is byte-for-byte (NOT ASCII-normalized), so it survives piping

package/clients/cli/formatters/index.test.mjs

@@ -8,6 +8,9 @@ import {
   list,
   record,
   records,
+  wrapText,
+  displayWidth,
+  WRAP_WIDTH,
   code,
   Block,
   BULLET,
@@ -114,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');
   });
@@ -148,3 +157,91 @@ describe('emit', () => {
     expect(spy).not.toHaveBeenCalled();
   });
 });
+
+describe('wrapText', () => {
+  it('leaves short lines and its own line breaks alone', () => {
+    expect(wrapText('a b\nc')).toBe('a b\nc');
+  });
+
+  it('wraps at the width with a hanging indent', () => {
+    expect(wrapText('aaa bbb ccc', {width: 7, indent: '  '})).toBe('aaa bbb\n  ccc');
+  });
+
+  it('keeps a word longer than the width whole', () => {
+    expect(wrapText('x '.concat('y'.repeat(20)), {width: 10})).toBe(
+      `x\n${'y'.repeat(20)}`,
+    );
+  });
+});
+
+describe('records inline layout', () => {
+  const items = [
+    {id: 'a', title: 'Alpha', summary: 'First.'},
+    {id: 'bbb', title: 'Beta', summary: ''},
+  ];
+
+  it('puts one record on each line under a padded first column', () => {
+    expect(
+      records(items, {fields: ['id', 'title', 'summary'], layout: 'inline'}).toString(),
+    ).toBe('a    Alpha - First.\nbbb  Beta');
+  });
+
+  it('wraps a long record under the first column', () => {
+    const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+      layout: 'inline',
+    }).toString();
+    expect(out.split('\n').length).toBeGreaterThan(1);
+    expect(out.split('\n').every(line => line.length <= WRAP_WIDTH)).toBe(true);
+    expect(out.split('\n')[1].startsWith('   word')).toBe(true);
+  });
+
+  it('keeps the first column padded on a record that wraps', () => {
+    const out = records(
+      [
+        {id: 'a', text: 'word '.repeat(40).trim()},
+        {id: 'longer', text: 'x'},
+      ],
+      {layout: 'inline'},
+    ).toString();
+    const lines = out.split('\n');
+    expect(lines[0].startsWith(`a${' '.repeat(7)}word`)).toBe(true);
+    expect(lines[1].startsWith(' '.repeat(8) + 'word')).toBe(true);
+    expect(lines.at(-1)).toBe('longer  x');
+    expect(lines.every(line => line.length <= WRAP_WIDTH)).toBe(true);
+  });
+
+  it('cuts a long record to one line when asked', () => {
+    const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+      layout: 'inline',
+      overflow: 'truncate',
+    }).toString();
+    expect(out.includes('\n')).toBe(false);
+    expect(out.length).toBeLessThanOrEqual(WRAP_WIDTH);
+    expect(out.endsWith('...')).toBe(true);
+  });
+});
+
+describe('wide characters', () => {
+  it('counts CJK characters as two columns', () => {
+    expect(displayWidth('亮/暗模式')).toBe(9);
+  });
+
+  it('wraps CJK text, which has no spaces, by columns', () => {
+    const out = wrapText('中'.repeat(100), {width: 20});
+    expect(out.split('\n').every(line => displayWidth(line) <= 20)).toBe(true);
+    expect(out.split('\n')).toHaveLength(10);
+  });
+
+  it('keeps spaces between Latin words next to CJK', () => {
+    expect(wrapText('运行 astryx docs 查看', {width: 200})).toBe('运行 astryx docs 查看');
+  });
+
+  it('cuts an inline record to columns, not characters', () => {
+    const out = records([{id: 'a', text: '中'.repeat(100)}], {
+      layout: 'inline',
+      overflow: 'truncate',
+    }).toString();
+    expect(displayWidth(out)).toBeLessThanOrEqual(WRAP_WIDTH);
+    expect(out.endsWith('...')).toBe(true);
+  });
+});