@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

package/clients/cli/commands/docs.mjs

@@ -3,29 +3,18 @@
 /**
  * @file docs command — Print Astryx reference docs
  *
- * A topic prints its whole doc; `--index` lists its sections instead, so a
- * reader can open one section by its key.
+ * Auto-discovers .doc.mjs files from the docs/ directory.
  * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
  *
  * Usage:
  *   astryx docs                          List available topics
- *   astryx docs <topic>                  Print the whole topic
- *   astryx docs <topic> --index          List the topic's sections
+ *   astryx docs <topic>                  Print full doc
  *   astryx docs <topic> <section>        Print one section
  */
 
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {
-  emit,
-  section,
-  records,
-  text,
-  code,
-  wrapText,
-  displayWidth,
-  WRAP_WIDTH,
-} from '../formatters/index.mjs';
+import {emit, section, records, text, code} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {resultSet} from '../../../foundation/debug/index.mjs';
@@ -52,28 +41,6 @@ function formatTable(headers, rows) {
   return `${head}\n${sep}\n${body}`;
 }
 
-/**
- * A table too wide for {@link WRAP_WIDTH}: one `header: cell` line per cell and
- * a blank line between rows, so nothing runs off the side of a terminal.
- * @param {string[]} headers
- * @param {string[][]} rows
- * @returns {string}
- */
-function formatTableVertical(headers, rows) {
-  const width = Math.max(...headers.map(h => h.length)) + 2;
-  return rows
-    .map(row =>
-      headers
-        .map((h, i) =>
-          wrapText(`${`${h}:`.padEnd(width)}${row[i] ?? ''}`, {
-            indent: ' '.repeat(width),
-          }),
-        )
-        .join('\n'),
-    )
-    .join('\n\n');
-}
-
 /**
  * @param {string[]} headers
  * @param {string[][]} rows
@@ -91,7 +58,7 @@ function formatTableCompact(headers, rows) {
 function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
-      return wrapText(block.text);
+      return block.text;
 
     case 'heading':
       return `${'#'.repeat(block.level || 3)} ${block.text}`;
@@ -110,37 +77,16 @@ function formatBlock(block, detail) {
       if (detail === 'compact') {
         return formatTableCompact(block.headers, block.rows);
       }
-      {
-        const table = formatTable(block.headers, block.rows);
-        return table.split('\n').some(line => displayWidth(line) > WRAP_WIDTH)
-          ? formatTableVertical(block.headers, block.rows)
-          : table;
-      }
+      return formatTable(block.headers, block.rows);
 
     case 'list': {
-      const prefix =
-        block.style === 'ordered'
-          ? (/** @type {number} */ i) => `${i + 1}. `
-          : block.style === 'dont'
-            ? () => 'x '
-            : block.style === 'do'
-              ? () => '+ '
-              : () => '- ';
-      return block.items
-        .map((item, i) => {
-          const head = prefix(i);
-          return wrapText(`${head}${item}`, {indent: ' '.repeat(head.length)});
-        })
-        .join('\n');
+      const prefix = block.style === 'ordered' ? (/** @type {number} */ i) => `${i + 1}. `
+        : block.style === 'dont' ? () => 'x '
+        : block.style === 'do' ? () => '+ '
+        : () => '- ';
+      return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
     }
 
-    case 'workflow':
-    case 'collection':
-    case 'reference':
-      throw new Error(
-        `Documentation block "${block.type}" requires the compiled graph renderer.`,
-      );
-
     default:
       return null;
   }
@@ -161,8 +107,7 @@ function formatSection(section, detail) {
     return `${section.title}: ${first.split('\n')[0]}`;
   }
 
-  const heading =
-    detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
+  const heading = detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
   return `${heading}\n\n${blocks.join('\n\n')}`;
 }
 
@@ -173,51 +118,25 @@ function formatSection(section, detail) {
  */
 function formatReferenceFull(docs, detail) {
   if (detail === 'brief') {
-    const header = wrapText(`${docs.title}: ${docs.description}`);
+    const header = `${docs.title}: ${docs.description}`;
     const sections = docs.sections.map(s => formatSection(s, detail));
     return `${header}\n${sections.join('\n')}`;
   }
 
-  const description = wrapText(docs.description);
-  const header =
-    detail === 'compact'
-      ? `# ${docs.title}\n${description}`
-      : `# ${docs.title}\n\n${description}`;
+  const header = detail === 'compact'
+    ? `# ${docs.title}\n${docs.description}`
+    : `# ${docs.title}\n\n${docs.description}`;
   const sections = docs.sections.map(s => formatSection(s, detail));
   const sep = detail === 'compact' ? '\n\n' : '\n\n';
   return `${header}\n\n${sections.join(sep)}`;
 }
 
-/**
- * A topic's section index: what the topic is, one line per section with the
- * key to read it by, and how to read further.
- * @param {import('../../../api/docs/docs.type.mjs').DocsIndex} index
- * @param {string} run
- */
-function emitIndex(index, run) {
-  emit(
-    section(index.title, index.description ? wrapText(index.description) : undefined),
-    records(index.sections, {
-      fields: ['id', 'title', 'summary'],
-      layout: 'inline',
-      overflow: 'truncate',
-    }),
-    text(
-      [
-        `Read one section: ${run} docs ${index.name} <section>`,
-        `Read everything:  ${run} docs ${index.name}`,
-      ].join('\n'),
-    ),
-  );
-}
-
 /**
  * What the run answered with. A named topic (or one of its sections) resolves
  * or throws, so it is always a direct match of one doc; the bare form lists
  * every topic there is.
  *
  * @param {import('../../../api/docs/docs.type.mjs').DocsListResponse
- *   | import('../../../api/docs/docs.type.mjs').DocsIndexResponse
  *   | import('../../../api/docs/docs.type.mjs').DocsDetailResponse
  *   | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse} result
  * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
@@ -236,11 +155,7 @@ function summarize(result) {
 export function registerDocs(program) {
   defineCommand(program, docsCommand, {
     fn: docsFn,
-    action: async (
-      /** @type {string | undefined} */ topic,
-      /** @type {string | undefined} */ sectionName,
-      /** @type {{index?: boolean}} */ options = {},
-    ) => {
+    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;
@@ -250,17 +165,11 @@ export function registerDocs(program) {
 
       let result;
       try {
-        result = await docsApi(topic, sectionName, {
-          lang,
-          zh,
-          dense,
-          index: Boolean(options.index),
-        });
+        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.
-        const err =
-          /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
         return cliError(err.message, {
           suggestions: err.suggestions || [],
           code: err.code,
@@ -279,26 +188,17 @@ export function registerDocs(program) {
           // description), then the usage footer as plain prose.
           emit(
             section('Available docs'),
-            records(result.data, {
-              fields: ['topic', 'description'],
-              layout: 'inline',
-            }),
+            records(result.data, {fields: ['topic', 'description']}),
             text(
               [
-                `Usage: ${run} docs <topic>                  read the whole topic`,
-                `       ${run} docs <topic> --index          list its sections`,
-                `       ${run} docs <topic> <section>        read one section`,
+                `Usage: ${run} docs <topic>`,
+                `       ${run} docs <topic> <section>`,
               ].join('\n'),
             ),
           );
           break;
         }
 
-        case 'docs.index': {
-          emitIndex(result.data, run);
-          break;
-        }
-
         case 'docs.detail': {
           emit(code(formatReferenceFull(result.data, detail)));
           break;

package/clients/cli/commands/docs.test.mjs

@@ -6,8 +6,6 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {Command} from 'commander';
 import {registerDocs} from './docs.mjs';
-import {runCli} from '../../../test-utils/run-cli.mjs';
-import {displayWidth} from '../formatters/index.mjs';
 
 let tmpDir;
 
@@ -102,89 +100,3 @@ describe('migration docs', () => {
     expect(output).toContain('Map shadcn and Radix Primitives');
   });
 });
-
-describe('progressive reads', () => {
-  const SLOW = 60_000;
-  /** @param {string} out */
-  const widest = out => Math.max(...out.split('\n').map(line => line.length));
-
-  it('lists every topic on one line each', async () => {
-    const {status, stdout} = await runCli(['docs']);
-    expect(status).toBe(0);
-    expect(stdout).toMatch(/^principles +\S/m);
-    expect(widest(stdout)).toBeLessThanOrEqual(120);
-  }, SLOW);
-
-  it("prints a topic's section index with the keys to read by", async () => {
-    const {status, stdout} = await runCli(['docs', 'theme', '--index']);
-    expect(status).toBe(0);
-    expect(stdout).toMatch(/^quick-start +Quick Start/m);
-    expect(stdout).toContain('docs theme <section>');
-    expect(stdout).toMatch(/Read everything: +\S.* docs theme$/m);
-    expect(widest(stdout)).toBeLessThanOrEqual(120);
-  }, SLOW);
-
-  it('prints one section by its key', async () => {
-    const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
-    expect(status).toBe(0);
-    expect(stdout).toMatch(/^## Quick Start/m);
-  }, SLOW);
-
-  it('prints the whole topic by default, as before', async () => {
-    const index = await runCli(['docs', 'theme', '--index']);
-    const full = await runCli(['docs', 'theme']);
-    expect(full.status).toBe(0);
-    expect(full.stdout).toMatch(/^## Quick Start/m);
-    expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
-    expect((await runCli(['--detail', 'full', 'docs', 'theme'])).stdout).toBe(
-      full.stdout,
-    );
-    expect(widest(full.stdout.replace(/```[\s\S]*?```/g, ''))).toBeLessThanOrEqual(
-      120,
-    );
-  }, SLOW);
-
-  it('returns the matching envelopes as JSON', async () => {
-    const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);
-    expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');
-    expect((await envelope(['docs', 'theme', '--index'])).type).toBe(
-      'docs.index',
-    );
-    expect((await envelope(['docs', 'theme', 'quick-start'])).type).toBe(
-      'docs.detail.section',
-    );
-  }, SLOW);
-});
-
-describe('text width in every language', () => {
-  const SLOW = 60_000;
-  /** Widest line outside code blocks, in terminal columns. */
-  const widest = out => {
-    let inCode = false;
-    let max = 0;
-    for (const line of out.split('\n')) {
-      if (/^\s*```/.test(line)) {
-        inCode = !inCode;
-        continue;
-      }
-      // A single unbreakable token (a long URL) cannot wrap without breaking it.
-      const oneToken = !/\s/.test(line.trim());
-      if (!inCode && !line.startsWith('#') && !oneToken) {
-        max = Math.max(max, displayWidth(line));
-      }
-    }
-    return max;
-  };
-
-  it.each([
-    [['docs', 'theme', '--index', '--lang', 'zh']],
-    [['docs', 'theme', '--lang', 'zh']],
-    [['--detail', 'full', 'docs', 'theme', '--lang', 'zh']],
-    [['--detail', 'full', 'docs', 'internationalization']],
-    [['--detail', 'full', 'docs', 'styling']],
-  ])('%j fits in 120 columns', async args => {
-    const {status, stdout} = await runCli(args);
-    expect(status).toBe(0);
-    expect(widest(stdout)).toBeLessThanOrEqual(120);
-  }, SLOW);
-});

package/clients/cli/commands/integration-authoring.test.mjs

@@ -120,7 +120,7 @@ describe('integration authoring CLI', () => {
     );
   });
 
-  it('pack-check rejects a generated component without an exports map (no-map false green)', async () => {
+  it('packs the generated contribution and proves the consumer inventory', async () => {
     const added = await runCli(
       ['integration', 'add', 'component', 'AcmeWidget', '--json'],
       tmpDir,
@@ -131,23 +131,19 @@ describe('integration authoring CLI', () => {
       ['integration', 'pack', '--check', '--json'],
       tmpDir,
     );
-    // Without an exports map, the extensionless import cannot resolve —
-    // pack-check must fail, not false-green.
-    expect(checked.status).not.toBe(0);
-    const envelope = parseEnvelope(checked.stdout);
-    expect(envelope).toMatchObject({
+    expect(checked.status).toBe(0);
+    expect(parseEnvelope(checked.stdout)).toMatchObject({
       type: 'integration.pack-check',
       data: {
         name: '@acme/widgets',
-        packable: false,
+        version: '1.0.0',
+        packable: true,
+        contributions: {
+          local: {components: ['AcmeWidget']},
+          packed: {components: ['AcmeWidget']},
+        },
       },
     });
-    expect(envelope.data.issues).toContainEqual(
-      expect.objectContaining({
-        severity: 'error',
-        message: expect.stringContaining('AcmeWidget'),
-      }),
-    );
   });
 
   it('requires the explicit --check gate on pack', async () => {

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -18,11 +18,7 @@ export const doc = {
     'Without --out it prints a preview. With --out it writes a candidate file and detached ' +
     'receipt. --preview writes a standardized, self-contained HTML review artifact. ' +
     'TypeScript output is directly importable and contains no generator dependency. ' +
-    'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit. ' +
-    'When used in a theme integration, keep the palette request under the theme slug, ' +
-    'write the candidate and receipt under that same slug, import the candidate from the theme source, ' +
-    "and list all three paths in the theme catalog entry's `files` array " +
-    'so `astryx theme add` copies them into the consumer project.',
+    'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit.',
   fn: 'themePaletteGenerate',
   args: [{name: 'config', param: 'configPath', required: true}],
   options: [
@@ -46,15 +42,15 @@ export const doc = {
   examples: [
     {
       label: 'Preview candidate JSON',
-      cli: 'astryx theme palette generate themes/ocean/palette.config.json',
+      cli: 'astryx theme palette generate palette.config.json',
     },
     {
       label: 'Write candidate and receipt',
-      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',
+      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts',
     },
     {
       label: 'Write candidate, receipt, and review preview',
-      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts --preview themes/ocean/tokens/ocean.palette.html',
+      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts --preview ocean.palette.html',
     },
   ],
   exitCodes: [

package/clients/cli/commands/upgrade.doc.mjs

@@ -53,10 +53,10 @@ export const doc = {
         'Exclude named codemods (repeatable). Re-run past a failed codemod by skipping it.',
     },
     {
-      flag: '--integration <package>',
+      flag: '--integration <package-or-file>',
       param: 'options.integration',
       description:
-        'Explicit integration specifier (repeatable). Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',
+        'Explicit integration package name or integration file path (repeatable)',
       default: [],
     },
     {

package/clients/cli/formatters/index.mjs

@@ -11,8 +11,7 @@
  * which fields to show and in what order.
  *
  * Constraints (deliberately narrow):
- *   - 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
+ *   - 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')`).
@@ -34,50 +33,6 @@ 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
@@ -112,13 +67,6 @@ 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} */
@@ -155,72 +103,6 @@ function toAscii(s) {
     .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
@@ -295,53 +177,10 @@ 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