@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/clients/cli/commands/docs.mjs

@@ -23,8 +23,6 @@ import {
   text,
   code,
   wrapText,
-  displayWidth,
-  WRAP_WIDTH,
 } from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
@@ -52,28 +50,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 +67,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,12 +86,7 @@ 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 =
@@ -126,21 +97,9 @@ function formatBlock(block, detail) {
             : block.style === 'do'
               ? () => '+ '
               : () => '- ';
-      return block.items
-        .map((item, i) => {
-          const head = prefix(i);
-          return wrapText(`${head}${item}`, {indent: ' '.repeat(head.length)});
-        })
-        .join('\n');
+      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;
   }
@@ -173,16 +132,15 @@ 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}`;
+      ? `# ${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)}`;
@@ -196,7 +154,10 @@ function formatReferenceFull(docs, detail) {
  */
 function emitIndex(index, run) {
   emit(
-    section(index.title, index.description ? wrapText(index.description) : undefined),
+    section(
+      index.title,
+      index.description ? wrapText(index.description) : undefined,
+    ),
     records(index.sections, {
       fields: ['id', 'title', 'summary'],
       layout: 'inline',
@@ -275,19 +236,15 @@ export function registerDocs(program) {
 
       switch (result.type) {
         case 'docs.list': {
-          // The text view mirrors the JSON list: one record per topic (topic +
-          // description), then the usage footer as plain prose.
+          // Keep the published 0.6 text projection: stacked topic and
+          // description fields, followed by the two original usage lines.
           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'),
             ),
           );

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

@@ -108,11 +108,11 @@ describe('progressive reads', () => {
   /** @param {string} out */
   const widest = out => Math.max(...out.split('\n').map(line => line.length));
 
-  it('lists every topic on one line each', async () => {
+  it('keeps the 0.6.x stacked topic list', async () => {
     const {status, stdout} = await runCli(['docs']);
     expect(status).toBe(0);
-    expect(stdout).toMatch(/^principles +\S/m);
-    expect(widest(stdout)).toBeLessThanOrEqual(120);
+    expect(stdout).toMatch(/^topic: +principles$/m);
+    expect(stdout).toContain('Usage: pnpm exec astryx docs <topic>');
   }, SLOW);
 
   it("prints a topic's section index with the keys to read by", async () => {
@@ -139,9 +139,6 @@ describe('progressive reads', () => {
     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 () => {
@@ -176,14 +173,14 @@ describe('text width in every language', () => {
     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);
+  it('keeps the additive section index within 120 columns', async () => {
+    const {status, stdout} = await runCli([
+      'docs',
+      'theme',
+      '--index',
+      '--lang',
+      'zh',
+    ]);
     expect(status).toBe(0);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
   }, SLOW);

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration components',
   displayName: 'astryx doctor integration components',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Warn when integration component names conflict with Core',
   description:
     'Compares one local or installed integration with Core component names. A ' +

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration docs',
   displayName: 'astryx doctor integration docs',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Classify integration doc overlaps with Core topics',
   description:
     'Reports intentional Core topic replacements and extensions as information. ' +

package/clients/cli/commands/doctor-integration-templates.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration templates',
   displayName: 'astryx doctor integration templates',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Warn when integration template ids conflict with Core',
   description:
     'Compares one local or installed integration with the built-in Core page and ' +

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration validate',
   displayName: 'astryx doctor integration validate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Validate an integration manifest and its contributions',
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +

package/clients/cli/commands/doctor-integration.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration',
   displayName: 'astryx doctor integration',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Check an integration package while authoring it',
   description:
     'The integration-authoring diagnostics group. Validate a manifest and all ' +

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

@@ -44,7 +44,7 @@ function writeIntegration({
   const stem = path.join(tmpDir, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
+    `${stem}.doc.mjs`,
     `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
   );
   fs.writeFileSync(
@@ -124,7 +124,12 @@ describe('doctor integration — command', () => {
       return true;
     });
 
-    await createProgram().parseAsync(['node', 'astryx', 'doctor', 'integration']);
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+    ]);
 
     const output = writes.join('');
     expect(output).toContain('validate [package]');
@@ -136,7 +141,9 @@ describe('doctor integration — command', () => {
 
   it('explains the optional package argument in every leaf help', () => {
     const program = createProgram();
-    const doctor = program.commands.find(command => command.name() === 'doctor');
+    const doctor = program.commands.find(
+      command => command.name() === 'doctor',
+    );
     const integration = doctor?.commands.find(
       command => command.name() === 'integration',
     );
@@ -152,7 +159,10 @@ describe('doctor integration — command', () => {
   });
 
   it('templates explains how to check an installed package when no local manifest exists', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
     process.chdir(tmpDir);
 
     await createProgram().parseAsync([
@@ -278,9 +288,7 @@ describe('doctor integration — command', () => {
     const output = logCalls.join('\n');
     expect(output).toContain('[warn]');
     expect(output).toContain(core.name);
-    expect(output).toContain(
-      `component ${core.name} --package @acme/widgets`,
-    );
+    expect(output).toContain(`component ${core.name} --package @acme/widgets`);
     expect(process.exitCode).toBeUndefined();
   });
 

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'doctor',
   displayName: 'astryx doctor',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +

package/clients/cli/commands/gap-report.doc.mjs

@@ -10,7 +10,7 @@ export const doc = {
   type: 'command',
   name: 'gap-report',
   displayName: 'astryx gap-report',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Route a design-system gap to its owning package',
   description:
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'hook',
   displayName: 'astryx hook',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List hooks or print hook docs',
   description:
     'Resolves a hook by name and prints its authored doc, or lists the catalog grouped ' +

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'init',
   displayName: 'astryx init',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +

package/clients/cli/commands/integration-add.controls.test.mjs

@@ -126,7 +126,7 @@ describe('integration add control definitions', () => {
     );
     expect(page.status).toBe(0);
     expect(
-      fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.template.mjs'), 'utf-8'),
+      fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.doc.mjs'), 'utf-8'),
     ).toContain("type: 'page'");
   });
 });

package/clients/cli/commands/integration-add.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration add',
   displayName: 'astryx integration add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Add one working contribution to an integration package',
   description:
     'Writes the complete minimum shape the selected contribution needs, creates the integration manifest on first use, declares the root only after a valid contribution exists, and verifies the result through the same discovery contract the packed-package check uses.',

package/clients/cli/commands/integration-pack.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration pack',
   displayName: 'astryx integration pack',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Prove the packed integration is what consumers receive',
   description:
     'Runs the package lifecycle, packs with npm, checks every required contribution file against the real tarball, extracts it into a scratch consumer, and compares the local and packed contribution inventories through one shared contract.',

package/clients/cli/commands/integration-real-world.test.mjs

@@ -201,13 +201,6 @@ export const oceanTheme = defineTheme({
 });
 `,
     );
-    const catalogFile = path.join(providerDir, 'themes', 'manifest.json');
-    const catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
-    catalog.themes[0].files.push(
-      'tokens/ocean.palette.ts',
-      'tokens/ocean.palette.receipt.json',
-    );
-    writeJson(catalogFile, catalog);
 
     const providerPackage = JSON.parse(
       fs.readFileSync(path.join(providerDir, 'package.json'), 'utf-8'),
@@ -464,8 +457,9 @@ export const oceanTheme = defineTheme({
         outputDir: target,
         files: [
           'oceanTheme.ts',
-          'tokens/ocean.palette.ts',
+          'oceanTheme.doc.mjs',
           'tokens/ocean.palette.receipt.json',
+          'tokens/ocean.palette.ts',
         ],
       },
     });
@@ -612,7 +606,7 @@ export const oceanTheme = defineTheme({
     expect(corruptedInstall.status).not.toBe(0);
     expect(parseEnvelope(corruptedInstall.stdout)).toMatchObject({
       code: 'ERR_THEME_INVALID',
-      error: expect.stringContaining('ocean.palette.ts'),
+      error: expect.stringContaining('./tokens/ocean.palette'),
     });
   }, 120_000);
 });

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

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration',
   displayName: 'astryx integration',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
     'Add contributions that are valid on arrival, then prove the packed package exposes the same contributions a consumer will receive.',

package/clients/cli/commands/layout-check.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout check',
   displayName: 'astryx layout check',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Validate a layout expression and echo canonical compact/outline forms',
   description:

package/clients/cli/commands/layout-expand.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout expand',
   displayName: 'astryx layout expand',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +

package/clients/cli/commands/layout-grammar.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout grammar',
   displayName: 'astryx layout grammar',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
   description:

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'layout',
   displayName: 'astryx layout',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'manifest',
   displayName: 'astryx manifest',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'search',
   displayName: 'astryx search',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
     'Terminal front-end to search(): prints one ranked, greppable list across ' +

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'swizzle',
   displayName: 'astryx swizzle',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Copy component source for customization',
   description:
     "Ejects a component's source from the resolved @astryxdesign/core (or its owning " +

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'template',
   displayName: 'astryx template',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Inject a page or block template',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +