@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/authoring/integration/type.ts

@@ -3,9 +3,10 @@
 /**
  * Public type surface for an Astryx integration manifest
  * (`astryx.integration.{ts,mjs,js}`, sibling to the integration package's
- * package.json). Identity (name/version) comes from package.json, not the
- * manifest. Authors write a plain object against {@link AstryxIntegration};
- * the CLI validates it via `parseIntegration` at the load boundary.
+ * package.json). Identity defaults to the package name, but `providerId` can keep
+ * a stable logical identity across an explicit package rename. Authors write a
+ * plain object against {@link AstryxIntegration}; the CLI validates it via
+ * `parseIntegration` at the load boundary.
  *
  * The manifest module may also carry `debug` and `gapReport` NAMED exports.
  * They are not fields here on purpose: a CLI released before a given manifest
@@ -13,11 +14,20 @@
  * named export is simply not read. See the `cli-integrations` doc topic.
  */
 export interface AstryxIntegration {
+  /** Stable logical provider ID. Omit to use package.json#name. Set this only
+   *  when a package rename must preserve existing artifact IDs. */
+  providerId?: string;
   /** Relative path to the components/docs root (resolved to absolute). */
   components?: string;
   /** Relative path to the templates root (resolved to absolute). */
   templates?: string;
-  /** Relative path to the codemods root (resolved to absolute). */
+  /** Relative path to the codemods root (resolved to absolute).
+   *  The root uses a version-folder-first layout:
+   *  `<codemodsRoot>/<version>/<id>.<ext>`, where `<version>` is an exact
+   *  semver string (e.g. `0.2.0`, no `v` prefix) and `<id>` is a kebab-case
+   *  module basename. Each module default-exports a codemod envelope stamped
+   *  `type: 'code'` or `type: 'config'`. Codemod ids must be unique within
+   *  a package across all versions. */
   codemods?: string;
   /** Relative path to the reference-docs (topics) root (resolved to
    *  absolute). Every `{topic}.doc.{ts,mjs,js}` under it is a topic the CLI
@@ -25,7 +35,14 @@ export interface AstryxIntegration {
    *  `replace` or `extend` a built-in topic; see the ReferenceDoc type. */
   docs?: string;
   /** Relative path to the source-theme catalog root (resolved to absolute).
-   *  The root contains `manifest.json` plus one directory per theme slug. */
+   *  The root contains `manifest.json` plus one directory per theme slug.
+   *  `manifest.json` is `{ "version": 1, "themes": [...] }` where each
+   *  entry requires `slug`, `displayName`, `description` (string),
+   *  `maintained` (boolean), `entry` (source file relative to `themes/<slug>/`),
+   *  `exportName` (a valid JS identifier naming the runtime export), and
+   *  `files` (non-empty array of filenames relative to `themes/<slug>/`).
+   *  Every file listed must exist on disk; the entry file must also appear
+   *  in `files`. */
   themes?: string;
   /** Static package guidance appended to the CLI-owned managed agent block. */
   agentDocs?: {
@@ -49,4 +66,4 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from '../gap-report/type';
+} from '../gap-report/type.js';

package/authoring/shadcn/receipt.d.mts

@@ -63,7 +63,7 @@ export function createRegistryReceipt(input: {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -83,7 +83,7 @@ export function createRegistryReceipt(input: {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -112,7 +112,7 @@ export function parseRegistryReceipt(input: unknown): {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -132,7 +132,7 @@ export function parseRegistryReceipt(input: unknown): {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -165,8 +165,8 @@ export const registryReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         path: z.ZodString;
         aliases: z.ZodArray<z.ZodString>;
         kind: z.ZodEnum<{
-            block: "block";
             page: "page";
+            block: "block";
             example: "example";
             showcase: "showcase";
         }>;
@@ -190,8 +190,8 @@ export const registryReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         path: z.ZodString;
         aliases: z.ZodArray<z.ZodString>;
         kind: z.ZodEnum<{
-            block: "block";
             page: "page";
+            block: "block";
             example: "example";
             showcase: "showcase";
         }>;

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

@@ -16,22 +16,32 @@ export const doc = {
   summary: 'Print reference docs',
   description:
     'Reads the reference docs: with no topic it lists every topic; a topic prints that ' +
-    'full doc; a topic plus a section returns the first section whose title contains the ' +
-    '(case-insensitive) query.',
+    'full doc; `--index` lists its sections instead, each with the key to read it by; a ' +
+    'topic plus a section prints that section (by key, exact title, or a unique part of ' +
+    'a title).',
   fn: 'docs',
   args: [
     {name: 'topic', param: 'topic', required: false},
     {name: 'section', param: 'section', required: false},
   ],
+  options: [
+    {
+      flag: '--index',
+      param: 'options.index',
+      description: "List the topic's sections and their keys instead of printing the whole topic",
+    },
+  ],
   examples: [
     {label: 'List topics', cli: 'astryx docs'},
     {label: 'One topic as JSON', cli: 'astryx docs spacing --json'},
+    {label: "A topic's sections", cli: 'astryx docs theme --index'},
+    {label: 'One section', cli: 'astryx docs theme quick-start'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown topic, or a section that matches no title in the topic',
+      when: 'unknown topic, or a section that matches no section or more than one',
     },
   ],
   related: ['search', 'component', 'hook', 'template'],

package/clients/cli/commands/docs.mjs

@@ -3,18 +3,29 @@
 /**
  * @file docs command — Print Astryx reference docs
  *
- * Auto-discovers .doc.mjs files from the docs/ directory.
+ * A topic prints its whole doc; `--index` lists its sections instead, so a
+ * reader can open one section by its key.
  * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
  *
  * Usage:
  *   astryx docs                          List available topics
- *   astryx docs <topic>                  Print full doc
+ *   astryx docs <topic>                  Print the whole topic
+ *   astryx docs <topic> --index          List the topic's sections
  *   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} from '../formatters/index.mjs';
+import {
+  emit,
+  section,
+  records,
+  text,
+  code,
+  wrapText,
+  displayWidth,
+  WRAP_WIDTH,
+} 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';
@@ -41,6 +52,28 @@ 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
@@ -58,7 +91,7 @@ function formatTableCompact(headers, rows) {
 function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
-      return block.text;
+      return wrapText(block.text);
 
     case 'heading':
       return `${'#'.repeat(block.level || 3)} ${block.text}`;
@@ -77,16 +110,37 @@ function formatBlock(block, detail) {
       if (detail === 'compact') {
         return formatTableCompact(block.headers, block.rows);
       }
-      return formatTable(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;
+      }
 
     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) => `${prefix(i)}${item}`).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) => {
+          const head = prefix(i);
+          return wrapText(`${head}${item}`, {indent: ' '.repeat(head.length)});
+        })
+        .join('\n');
     }
 
+    case 'workflow':
+    case 'collection':
+    case 'reference':
+      throw new Error(
+        `Documentation block "${block.type}" requires the compiled graph renderer.`,
+      );
+
     default:
       return null;
   }
@@ -107,7 +161,8 @@ 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')}`;
 }
 
@@ -118,25 +173,51 @@ function formatSection(section, detail) {
  */
 function formatReferenceFull(docs, detail) {
   if (detail === 'brief') {
-    const header = `${docs.title}: ${docs.description}`;
+    const header = wrapText(`${docs.title}: ${docs.description}`);
     const sections = docs.sections.map(s => formatSection(s, detail));
     return `${header}\n${sections.join('\n')}`;
   }
 
-  const header = detail === 'compact'
-    ? `# ${docs.title}\n${docs.description}`
-    : `# ${docs.title}\n\n${docs.description}`;
+  const description = wrapText(docs.description);
+  const header =
+    detail === 'compact'
+      ? `# ${docs.title}\n${description}`
+      : `# ${docs.title}\n\n${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}
@@ -155,7 +236,11 @@ function summarize(result) {
 export function registerDocs(program) {
   defineCommand(program, docsCommand, {
     fn: docsFn,
-    action: async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ sectionName) => {
+    action: async (
+      /** @type {string | undefined} */ topic,
+      /** @type {string | undefined} */ sectionName,
+      /** @type {{index?: boolean}} */ options = {},
+    ) => {
       const run = getCliInvocation();
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
@@ -165,11 +250,17 @@ export function registerDocs(program) {
 
       let result;
       try {
-        result = await docsApi(topic, sectionName, {lang, zh, dense});
+        result = await docsApi(topic, sectionName, {
+          lang,
+          zh,
+          dense,
+          index: Boolean(options.index),
+        });
       } 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,
@@ -188,17 +279,26 @@ export function registerDocs(program) {
           // description), then the usage footer as plain prose.
           emit(
             section('Available docs'),
-            records(result.data, {fields: ['topic', 'description']}),
+            records(result.data, {
+              fields: ['topic', 'description'],
+              layout: 'inline',
+            }),
             text(
               [
-                `Usage: ${run} docs <topic>`,
-                `       ${run} docs <topic> <section>`,
+                `Usage: ${run} docs <topic>                  read the whole topic`,
+                `       ${run} docs <topic> --index          list its sections`,
+                `       ${run} docs <topic> <section>        read one 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,6 +6,8 @@ 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;
 
@@ -100,3 +102,89 @@ 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('packs the generated contribution and proves the consumer inventory', async () => {
+  it('pack-check rejects a generated component without an exports map (no-map false green)', async () => {
     const added = await runCli(
       ['integration', 'add', 'component', 'AcmeWidget', '--json'],
       tmpDir,
@@ -131,19 +131,23 @@ describe('integration authoring CLI', () => {
       ['integration', 'pack', '--check', '--json'],
       tmpDir,
     );
-    expect(checked.status).toBe(0);
-    expect(parseEnvelope(checked.stdout)).toMatchObject({
+    // 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({
       type: 'integration.pack-check',
       data: {
         name: '@acme/widgets',
-        version: '1.0.0',
-        packable: true,
-        contributions: {
-          local: {components: ['AcmeWidget']},
-          packed: {components: ['AcmeWidget']},
-        },
+        packable: false,
       },
     });
+    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,7 +18,11 @@ 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.',
+    '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.',
   fn: 'themePaletteGenerate',
   args: [{name: 'config', param: 'configPath', required: true}],
   options: [
@@ -42,15 +46,15 @@ export const doc = {
   examples: [
     {
       label: 'Preview candidate JSON',
-      cli: 'astryx theme palette generate palette.config.json',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json',
     },
     {
       label: 'Write candidate and receipt',
-      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',
     },
     {
       label: 'Write candidate, receipt, and review preview',
-      cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts --preview ocean.palette.html',
+      cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts --preview themes/ocean/tokens/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-or-file>',
+      flag: '--integration <package>',
       param: 'options.integration',
       description:
-        'Explicit integration package name or integration file path (repeatable)',
+        'Explicit integration specifier (repeatable). Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',
       default: [],
     },
     {