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

package/assets/docs/principles.doc.mjs

@@ -39,10 +39,10 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
-            'Page layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
+            'Page layout is frame-first: pick the shell and budget regions before writing content (see {@link generic:layout})',
             'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
-            'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
-            'Semantic tokens, not hardcoded values (see \`astryx docs tokens\`)',
+            'StyleX or Tailwind for custom styling; both are first-class (see {@link generic:styling})',
+            'Semantic tokens, not hardcoded values (see {@link generic:tokens})',
             'CSS custom properties for colors, not hex values',
             'Form inputs are controlled (value + onChange)',
             'Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider',
@@ -60,7 +60,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'See \`astryx docs styling\` for the complete guide with examples.',
+          text: 'See {@link generic:styling} for the complete guide with examples.',
         },
       ],
     },
@@ -76,7 +76,7 @@ export const docs = {
             'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
             'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
             'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
-            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`astryx docs layout\`)',
+            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see {@link generic:layout})',
             'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
             'Inventing props. Read component docs first',
           ],
@@ -89,7 +89,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`astryx docs tokens\` for the full reference with all values.',
+          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run {@link generic:tokens} for the full reference with all values.',
         },
       ],
     },

package/assets/docs/styling-libraries.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For available token names and values, run `astryx docs tokens`. Focused references are also available with `astryx docs color`, `astryx docs spacing`, `astryx docs shape`, `astryx docs typography`, `astryx docs elevation`, and `astryx docs motion`.',
+          text: 'For available token names and values, run {@link generic:tokens}. Focused references are also available with {@link generic:color}, {@link generic:spacing}, {@link generic:shape}, {@link generic:typography}, {@link generic:elevation}, and {@link generic:motion}.',
         },
       ],
     },
@@ -150,7 +150,7 @@ const styles = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme.',
+          text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme reference inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme without emitting competing runtime declarations.',
         },
         {
           type: 'code',
@@ -351,7 +351,7 @@ tokens: {
     },
   },
   shortcuts: {
-    'xds-card': 'bg-surface text-primary border border-border rounded-lg p-4',
+    'astryx-card': 'bg-surface text-primary border border-border rounded-lg p-4',
   },
 });`,
         },
@@ -455,7 +455,7 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
             'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.',
             'Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',
             'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',
-            'Use `astryx docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
+            'Use {@link generic:tokens} and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
             'Use token resolver APIs only for non-CSS APIs that need resolved values.',
           ],
         },

package/assets/docs/styling.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
         },
       ],
     },
@@ -118,7 +118,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `astryx docs styling-libraries`.',
+          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run {@link generic:styling-libraries}.',
         },
       ],
     },
@@ -263,7 +263,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `astryx docs theme` for the full theming guide.',
+          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run {@link generic:theme} for the full theming guide.',
         },
       ],
     },
@@ -338,7 +338,7 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'See `astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `astryx docs theme` for how to override tokens via defineTheme.',
+          text: 'See {@link generic:tokens} for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See {@link generic:theme} for how to override tokens via defineTheme.',
         },
       ],
     },

package/assets/docs/theme.doc.mjs

@@ -76,7 +76,7 @@ function App() {
             [
               'Neutral',
               "import {neutralTheme} from '@astryxdesign/theme-neutral'",
-              'Muted, minimal aesthetic with system fonts. A good starting point.',
+              'Muted, minimal aesthetic with Figtree typography. A good starting point.',
             ],
             [
               'Butter',
@@ -152,7 +152,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'The copy is editable project source, not a reference back into node_modules. Every file named by the theme catalog comes with it, including nested token or palette modules. A second add refuses to overwrite those files unless you pass `--overwrite`.',
+          text: 'The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`.',
         },
       ],
     },
@@ -391,7 +391,7 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
+          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in {@link generic:styling}.',
         },
         {
           type: 'code',
@@ -572,7 +572,7 @@ import './themes/ocean.css';
         },
         {
           type: 'prose',
-          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See `astryx docs typography` for the full recipe.",
+          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See {@link generic:typography} for the full recipe.",
         },
       ],
     },
@@ -811,7 +811,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
+          text: 'See {@link generic:styling-libraries} for styling-library interop and {@link generic:tokens} for the full token reference.',
         },
       ],
     },

package/assets/docs/tokens.doc.mjs

@@ -1102,7 +1102,7 @@ export const docs = {
         },
         {
           "type": "prose",
-          "text": "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme."
+          "text": "See {@link generic:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:theme} for overriding tokens with defineTheme."
         }
       ]
     }

package/assets/docs/tree/api.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/api`: the programmatic API of `@astryxdesign/cli/api`.
+ *
+ * Adopts each function, schema, and enum doc whose `namespace` is `cli/api`,
+ * one generated level per kind: `cli/api/functions`, `cli/api/schemas`, and
+ * `cli/api/enums`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'api',
+  title: 'API',
+  summary:
+    'The programmatic API: functions, the JSON output envelope, error codes, and response types.',
+  keywords: ['api', 'functions', 'schemas', 'enums', 'json'],
+  placement: {parent: 'namespace:cli', slot: 'reference', order: 20},
+  slots: {
+    kinds: {title: 'Reference', accepts: {kinds: ['namespace']}},
+  },
+  adopts: [
+    {
+      source: {group: 'cli/api', kinds: ['function', 'schema', 'enum']},
+      into: 'kinds',
+      groupBy: 'kind',
+    },
+  ],
+};

package/assets/docs/tree/cli.doc.mjs

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli`: the top of the CLI's docs tree (spec:AST-046).
+ *
+ * A namespace declares a level and its slots. It never lists its children:
+ * a guide places itself here with `placement`, and the `commands` and `api`
+ * namespaces adopt the CLI's typed docs by the `namespace` group each declares.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'cli',
+  title: 'Astryx CLI',
+  summary:
+    'Commands, programmatic APIs, integration authoring, and output contracts.',
+  keywords: ['cli', 'commands', 'api', 'reference'],
+  slots: {
+    guides: {title: 'Guides', accepts: {kinds: ['generic', 'namespace']}},
+    reference: {title: 'Reference', accepts: {kinds: ['namespace']}},
+  },
+};

package/assets/docs/tree/commands.doc.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/commands`: every command the CLI ships.
+ *
+ * Adopts each command doc whose `namespace` is `cli/commands`, so a new
+ * command appears here with no edit to this file.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'commands',
+  title: 'Commands',
+  summary:
+    'Every command and subcommand: usage, options, examples, and exit codes.',
+  keywords: ['commands', 'usage', 'options', 'flags'],
+  placement: {parent: 'namespace:cli', slot: 'reference', order: 10},
+  slots: {
+    commands: {title: 'Commands', accepts: {kinds: ['command']}},
+  },
+  adopts: [
+    {source: {group: 'cli/commands', kinds: ['command']}, into: 'commands'},
+  ],
+};

package/assets/docs/tree/component-lookups.doc.mjs

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/component-lookups`: exact single and batch component
+ * lookup through the CLI and programmatic API.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'component-lookups',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 5},
+  title: 'Looking up components',
+  category: 'guide',
+  description:
+    'Look up one or several exact component identities, choose a focused projection, and handle complete batch receipts.',
+  sections: [
+    {
+      id: 'several',
+      title: 'Look up several components',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: '`astryx component` accepts exact selectors as a variadic positional argument. With no selector it browses the catalog. With one selector it keeps the normal single-component response. With two or more it prints one complete ordered batch receipt.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Several component docs',
+          code: 'astryx component Button Badge Text\nastryx --json component Button Badge Text',
+        },
+        {
+          type: 'prose',
+          text: 'Every selector gets one row in input order. Duplicate selectors stay duplicate rows. A missing or ambiguous component does not hide successful neighbors or stop later selectors from resolving.',
+        },
+        {
+          type: 'prose',
+          text: 'A batch accepts at most 100 selectors, including duplicates, in every projection mode. A larger request returns a top-level `ERR_INVALID_ARGUMENT` before any component resolves. It emits no `component.batch` receipt and no partial results.',
+        },
+        {
+          type: 'prose',
+          text: 'Focused component controls apply to every found row. Use the same control you use for one component:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Focused batch lookups',
+          code: 'astryx --json component Button Card --props\nastryx component Button Card --source\nastryx component Button Card --showcase\nastryx component Button Card --blocks\nastryx component Button Card --detail compact\nastryx component Button Card --lang dense\nastryx component Button Card --package @astryxdesign/core',
+        },
+      ],
+    },
+    {
+      id: 'selectors',
+      title: 'Selector forms',
+      category: 'reference',
+      content: [
+        {
+          type: 'prose',
+          text: 'A selector is an exact component identity, not free-text search. Use one of these forms:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`Button` for an unqualified component name.',
+            '`widgets/Button` for a component in an unscoped package.',
+            '`@acme/widgets/Button` for a component in a scoped package.',
+            '`@acme/widgets@1.2.3/Button` to require that exact installed package version.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'A version qualifies the package, never the component. The lookup does not fall through to another installed version. An unqualified name owned by several installed packages is `ambiguous` and lists every candidate. Use a package-qualified selector or `--package` to choose one.',
+        },
+        {
+          type: 'prose',
+          text: '`astryx discover` remains free-text package discovery. Its words form one query; they are not component batch selectors.',
+        },
+      ],
+    },
+    {
+      id: 'output',
+      title: 'Batch output and exit status',
+      category: 'reference',
+      content: [
+        {
+          type: 'prose',
+          text: 'JSON uses `component.batch` with `{count, results}`. Each row echoes `selector` and has one status: `found`, `not_found`, `ambiguous`, or `error`. A found row carries the normal single-component `{type, data}` under `result`. Failed rows carry `code` and `error`, plus `suggestions` or `candidates` when available.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Outcome and duplicate examples',
+          code: 'astryx --json component Button Badge                 # all found, exit 0\nastryx --json component Button MissingWidget         # mixed, exit 1\nastryx --json component MissingWidget MissingPanel   # all failed, exit 1\nastryx --json component Button Button                # two ordered rows, exit 0',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'A complete failed JSON receipt',
+          code: 'astryx --json component MissingWidget MissingPanel',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: '{\n  "apiVersion": 1,\n  "type": "component.batch",\n  "data": {\n    "count": 2,\n    "results": [\n      {\n        "selector": "MissingWidget",\n        "status": "not_found",\n        "code": "ERR_UNKNOWN_COMPONENT",\n        "error": "No component named \\"MissingWidget\\""\n      },\n      {\n        "selector": "MissingPanel",\n        "status": "not_found",\n        "code": "ERR_UNKNOWN_COMPONENT",\n        "error": "No component named \\"MissingPanel\\""\n      }\n    ]\n  }\n}',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'The same receipt in text mode',
+          code: 'Component batch\n\ncount: 2\n\nResults\n\nMissingWidget\n\nselector: MissingWidget\nstatus:   not_found\ncode:     ERR_UNKNOWN_COMPONENT\nerror:    No component named "MissingWidget"\n\nMissingPanel\n\nselector: MissingPanel\nstatus:   not_found\ncode:     ERR_UNKNOWN_COMPONENT\nerror:    No component named "MissingPanel"',
+        },
+        {
+          type: 'prose',
+          text: 'The CLI emits every row first, then exits 1 when any row is not `found`. This includes mixed receipts and receipts where every row failed. JSON and text use the same exit status. A batch where every row is `found` exits 0.',
+        },
+      ],
+    },
+    {
+      id: 'api',
+      title: 'Programmatic API',
+      category: 'reference',
+      content: [
+        {
+          type: 'prose',
+          text: 'The argument shape chooses the response shape. Omit the argument for the catalog, pass a string for the existing single-component response, and pass an array for `component.batch`. An array always means batch, including empty and one-item arrays, so filtering a selector list cannot silently change the response type. The published `ComponentBatchResponse` specializes the shared `BatchResponse` and `BatchRow` types.',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "import {component} from '@astryxdesign/cli/api';\n\nconst catalog = await component(); // component.list\nconst button = await component('Button'); // component.detail\nconst empty = await component([]); // component.batch, count 0\nconst oneRow = await component(['Button']); // component.batch, count 1\nconst batch = await component(['Button', 'Badge']); // component.batch, count 2\nawait component(Array(101).fill('Button')); // ERR_INVALID_ARGUMENT before lookup",
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'Exact empty-array response',
+          code: '{\n  "type": "component.batch",\n  "data": {\n    "count": 0,\n    "results": []\n  }\n}',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'Handle every row without losing partial results',
+          code: "const receipt = await component(['Button', 'MissingWidget']);\n\nfor (const row of receipt.data.results) {\n  if (row.status === 'found') {\n    useComponentDoc(row.selector, row.result);\n  } else if (row.status === 'ambiguous') {\n    choosePackage(row.selector, row.candidates);\n  } else {\n    reportLookupFailure(row.selector, row.code, row.error);\n  }\n}",
+        },
+      ],
+    },
+  ],
+};