@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/checks`: what each package check
+ * proves, what fails and what only warns, and one command to run them all.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'checks',
+  placement: {parent: 'namespace:ship', slot: 'guides', order: 20},
+  title: 'Check an integration',
+  category: 'guide',
+  keywords: ['check before publishing', 'validate an integration', 'ci'],
+  description:
+    'Pick the check for each problem, learn what fails and what only warns, and run every check in CI.',
+  sections: [
+    {
+      id: 'pick-a-check',
+      title: 'Pick a check',
+      content: [
+        {
+          type: 'prose',
+          text: 'Run these in the package folder. The four `doctor integration` checks read your source; `integration verify` checks the package npm would publish.',
+        },
+        {
+          type: 'table',
+          headers: ['Command', 'Proves', 'Exits 1 when', 'Only warns when'],
+          rows: [
+            [
+              '`npx astryx doctor integration validate`',
+              'The manifest loads, and each root holds contributions the CLI can read',
+              'A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',
+              'The manifest has a key this CLI does not know (`unknown_manifest_key`). With no `astryx.integration.mjs` it prints a hint and exits 0',
+            ],
+            [
+              '`npx astryx doctor integration components`',
+              'No component name clashes with a Core component',
+              'Core is not installed (`core_not_found`)',
+              'A name clashes with Core',
+            ],
+            [
+              '`npx astryx doctor integration templates`',
+              'Each `replaces` names a Core template of the same type',
+              'A `replaces` target is missing (`missing_template_replacement_target`) or of the other type (`invalid_template_replacement`), or two templates replace one id (`ambiguous_template_replacement`)',
+              'A template id matches a Core id without `replaces`',
+            ],
+            [
+              '`npx astryx doctor integration docs`',
+              'Your docs tree, every link, and topic names against Core',
+              'A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)',
+              'A link names no doc (`invalid_doc_graph`)',
+            ],
+            [
+              '`npx astryx integration verify`',
+              'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
+              'Anything `validate` fails on, no manifest, a file left out of the `.tgz` file, an import that does not resolve, or a missing CLI peer',
+              'Anything `validate` warns about',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead.',
+        },
+      ],
+    },
+    {
+      id: 'run-every-check-in-ci',
+      title: 'Run every check in CI',
+      content: [
+        {
+          type: 'prose',
+          text: 'Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it.',
+            'Warnings keep exit code 0, so read them before you publish.',
+            'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'what-integration-verify-does',
+      title: 'Verify the packed package',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration verify` packs your package with npm, unpacks it into a temporary app, and checks that the app sees everything your source has. It publishes nothing and leaves no `.tgz` file or temporary folder behind.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'It runs `npm pack` the way `npm publish` would, including your `prepack` script.',
+            'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`',
+            'It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',
+            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",
+            'It fails a package that ships a docs section, a placed guide, a template `replaces`, a doc section with an `id`, or a theme without an `@astryxdesign/cli` peer of `>=0.7.0`.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: '`integration pack --check`, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
+        },
+      ],
+    },
+  ],
+};

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/codemods.doc.mjs

@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * integration package, and know which of them `astryx upgrade` runs in an app.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'codemods',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 50},
+  title: 'Codemods',
+  category: 'guide',
+  keywords: ['breaking change', 'migrate apps', 'integration codemod'],
+  description:
+    'Ship codemods that `astryx upgrade` runs to migrate app code, and know which of them an app runs.',
+  sections: [
+    {
+      id: 'add-a-codemod',
+      title: 'Add a codemod',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration add codemod` writes a codemod into a folder named after a version. Apps run it with `astryx upgrade` to migrate their code.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add codemod rename-delay --to 0.7.0',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `codemods/
+  0.7.0/
+    rename-delay.mjs         # the codemod
+    rename-delay.test.mjs    # skipped: a test file
+    __tests__/               # skipped: a test folder`,
+        },
+        {
+          type: 'prose',
+          text: "The first add declares `codemods: './codemods'` in `astryx.integration.mjs`. The codemod's id is its path inside the version folder, without the extension: `rename-delay`. An id must be unique across all version folders in the package.",
+        },
+        {
+          type: 'prose',
+          text: 'The loader skips `*.test.*`, `*.spec.*`, and `*.fixture.*` files and everything under `__tests__/` or `__fixtures__/`, so tests can sit beside the codemod. The folder name decides when an app runs the codemod; see "Choose when a codemod runs".',
+        },
+      ],
+    },
+    {
+      id: 'write-the-transform',
+      title: 'Write the transform',
+      content: [
+        {
+          type: 'prose',
+          text: 'A codemod default-exports a plain object with a `type`, a `title`, and a `transform` function. `transform` returns the new source, or `null` to leave the file as it is.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          code: `// codemods/0.7.0/rename-delay.mjs
+/** @type {import('@astryxdesign/cli/authoring').AstryxCodemod} */
+export default {
+  type: 'code',
+  title: 'Rename AcmeCarousel delay to interval',
+  description: 'Renames the delay prop on AcmeCarousel.',
+  fileExtensions: ['.tsx', '.jsx'],
+  transform(file, api) {
+    const j = api.jscodeshift;
+    const root = j(file.source);
+    const props = root
+      .find(j.JSXOpeningElement, {name: {name: 'AcmeCarousel'}})
+      .find(j.JSXAttribute, {name: {name: 'delay'}});
+    if (props.size() === 0) return null;
+    props.forEach(path => {
+      path.node.name.name = 'interval';
+    });
+    return root.toSource();
+  },
+};`,
+        },
+        {
+          type: 'prose',
+          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link generic:authoring}.",
+        },
+      ],
+    },
+    {
+      id: 'which-codemods-run',
+      title: 'Choose when a codemod runs',
+      content: [
+        {
+          type: 'prose',
+          text: "Two rules decide whether an app's `astryx upgrade` runs your codemods: the app's Core versions, and whether the app names your package.",
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            "Version folders are matched against the app's `@astryxdesign/core` versions, not your package's version. `upgrade --from <version>` runs each folder above `--from`, up to and including the Core version installed in the app. With Core 0.7.0 installed, `--from 0.6.3` runs `0.7.0/`, and `--from 0.7.0` runs nothing. A folder named after your own release, such as `1.0.0/`, waits until the app has Core 1.0.0.",
+            '`upgrade` runs your codemods only when the app lists your package in `integrations` in its `astryx.config`, or passes `--integration @acme/astryx-widgets`. Having your package installed is not enough: the run then skips your codemods with no warning.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'run-codemods-in-an-app',
+      title: 'Run codemods in an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'An app previews codemods with `astryx upgrade` and writes the changes with `--apply`. Without `--apply`, nothing on disk changes.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# Preview each codemod and the files it would change
+npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
+# Write the changes
+npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `Integrations: @acme/astryx-widgets
+1 codemod to run (dry run)
+Applying integration codemods...
+  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
+!     ~ src/Hero.tsx (would change)`,
+        },
+        {
+          type: 'prose',
+          text: "The count includes Core's codemods for the same versions, which run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
+        },
+        {
+          type: 'prose',
+          text: '`--from` is the Core version the app had before it upgraded. The run scans `./src` unless the app passes `--path`, and it never writes a file the app marks as generated, vendored, or ignored; see {@link command:upgrade}. `upgrade --list` shows only Core codemods.',
+        },
+        {
+          type: 'prose',
+          text: "An integration manifest has no `hooks` field. Commands that run after codemods, such as a formatter, are the app's to set, in `hooks.postCodemod` in its `astryx.config`.",
+        },
+      ],
+    },
+  ],
+};

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-family.doc.mjs

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * author one ComponentDoc for several public exports in a component family.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'component-family',
+  placement: {
+    parent: 'namespace:describe-the-component',
+    slot: 'guides',
+    order: 30,
+  },
+  title: 'Component family',
+  category: 'guide',
+  description:
+    'Adapt a single-component doc when one module exposes several public components or hooks that belong to one family.',
+  sections: [
+    {
+      id: 'choose-the-family-shape',
+      title: 'Choose the family shape',
+      content: [
+        {
+          type: 'prose',
+          text: 'Start with a complete single-component doc. Convert its top-level `props` into a `components` array only when one source module or component directory exposes several public components or hooks as one family. The family doc keeps the shared usage guidance; each array entry owns one public export.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Put the primary or most-used export first.',
+            'Use a full entry when this file owns that export\'s description and signature.',
+            'Use `props` for a component entry. Use `params` and `returns` for a hook entry.',
+            'Do not add private implementation helpers or exports that people should not use directly.',
+          ],
+        },
+        {
+          type: 'reference',
+          target: 'schema:component-doc',
+          projection: {fields: ['components']},
+          presentation: 'full',
+        },
+      ],
+    },
+    {
+      id: 'document-the-family-inline',
+      title: 'Document the family inline',
+      content: [
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'components/AcmeTabs.doc.mjs',
+          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+  type: 'component',
+  name: 'AcmeTabs',
+  displayName: 'Acme Tabs',
+  import: '@acme/astryx-widgets/components/AcmeTabs',
+  usage: {
+    description:
+      'Switches between related views without leaving the page.',
+  },
+  components: [
+    {
+      name: 'AcmeTabs',
+      displayName: 'Acme Tabs',
+      description: 'Owns selection and lays out the tab list and panels.',
+      props: [
+        {
+          name: 'value',
+          type: 'string',
+          description: 'The selected tab value.',
+          required: true,
+        },
+      ],
+    },
+    {
+      name: 'AcmeTab',
+      displayName: 'Acme Tab',
+      description: 'Selects one view in Acme Tabs.',
+      props: [
+        {
+          name: 'value',
+          type: 'string',
+          description: 'The value this tab selects.',
+          required: true,
+        },
+      ],
+    },
+  ],
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'The public module named by `import` must export every component or hook named by a full entry.',
+        },
+      ],
+    },
+    {
+      id: 'give-a-member-its-own-file',
+      title: 'Give a member its own file',
+      content: [
+        {
+          type: 'prose',
+          text: 'When one family member needs its own doc, replace its full entry with `{name: \'MemberName\'}` and move the details into a sibling doc. The parent keeps the family relationship without copying the child\'s content. Continue with {@link generic:subcomponent}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * integration component's documented import resolve from the packed package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'component-imports',
+  placement: {parent: 'namespace:components', slot: 'guides', order: 30},
+  title: 'Resolve the import',
+  category: 'guide',
+  description:
+    'Keep the component doc import and package exports map aligned, then verify the packed package.',
+  sections: [
+    {
+      id: 'export-the-component',
+      title: 'Export the component',
+      content: [
+        {
+          type: 'prose',
+          text: 'Apps copy the component doc\'s `import` field into their code, so that exact specifier must resolve from your packed package. `integration add` writes it together with an `exports` entry in package.json.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `"exports": {
+  "./components/AcmeCarousel": "./components/AcmeCarousel.tsx"
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
+        },
+      ],
+    },
+    {
+      id: 'verify-the-packed-import',
+      title: 'Verify the packed import',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration verify` installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration verify',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`component_import_unresolvable` means the exports map has no entry for the documented import.',
+            '`component_export_missing` means the module does not export the documented name, or package.json has no exports map.',
+            '`typescript_extension_in_specifier` means the public import ends in `.ts` or `.tsx`.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'To import from the package root, set `import: \'@acme/astryx-widgets\'` and re-export the component from the file that `exports["."]` points to. See {@link command:integration verify}.',
+        },
+      ],
+    },
+  ],
+};

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}",
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components`: guides for adding and
+ * documenting components in an integration package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'components',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 10},
+  title: 'Components',
+  summary:
+    'Add components to an integration, document their public contract, and make them work in every app that installs the package.',
+  keywords: ['integration component', 'ship a component', 'component docs'],
+  slots: {
+    guides: {
+      title: 'Components',
+      accepts: {kinds: ['generic', 'namespace']},
+    },
+  },
+};