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

package/foundation/response/response-types.doc.d.mts

@@ -4,8 +4,13 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
+ *
+ * @input Public response discriminants and their currently released payloads.
+ * @output Generated consumer reference for every typed JSON success response.
  * @position packages/cli/foundation/response — enum documentation
  */
 /** @type {import('@astryxdesign/cli/authoring').EnumDoc} */

package/foundation/response/response-types.doc.mjs

@@ -3,8 +3,13 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
+ *
+ * @input Public response discriminants and their currently released payloads.
+ * @output Generated consumer reference for every typed JSON success response.
  * @position packages/cli/foundation/response — enum documentation
  */
 
@@ -13,7 +18,7 @@ export const doc = {
   type: 'enum',
   name: 'response-types',
   displayName: 'Response Types',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'The `type` discriminant present on every --json success envelope. Consumers switch on it to narrow `data`.',
   members: [
@@ -31,12 +36,17 @@ export const doc = {
     {
       value: 'component.list',
       description:
-        'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.',
+        "The component catalog grouped by component group (each component's group field): `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.",
+    },
+    {
+      value: 'component.batch',
+      description:
+        'The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found | not_found | ambiguous | error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}).',
     },
     {
       value: 'component.detail',
       description:
-        "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).",
+        "One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).",
     },
     {
       value: 'component.detail.props',
@@ -61,17 +71,27 @@ export const doc = {
     {
       value: 'docs.list',
       description:
-        'All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.',
+        "All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.",
     },
     {
       value: 'docs.detail',
       description:
-        "One topic's full ReferenceDoc, with token-ref blocks inlined.",
+        "One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).",
+    },
+    {
+      value: 'docs.index',
+      description:
+        "One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).",
     },
     {
       value: 'docs.detail.section',
       description:
-        'A single ReferenceSection of a topic: the first whose title contains the section query.',
+        'One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).',
+    },
+    {
+      value: 'docs.node',
+      description:
+        "One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).",
     },
 
     // blog (read from the published RSS feed)
@@ -90,40 +110,46 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
-      description: 'A single external package entry, for an @scope/name query.',
+      description:
+        'One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.',
     },
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
+        'The validated ComponentDoc for one installed component, for an @scope/name/Component query.',
+    },
+    {
+      value: 'discover.item',
+      description:
+        'One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.',
     },
     {
       value: 'discover.search',
       description:
-        'The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.',
+        'The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.',
     },
 
     // search
     {
       value: 'search',
       description:
-        'The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).',
     },
 
     // build
     {
       value: 'build.help',
       description:
-        'A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.',
+        'The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.',
     },
     {
       value: 'build.kit',
       description:
-        'The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',
+        "The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.",
     },
 
     // swizzle
@@ -135,7 +161,7 @@ export const doc = {
     {
       value: 'swizzle.copy',
       description:
-        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.',
+        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
     },
 
     // gap reports
@@ -146,14 +172,14 @@ export const doc = {
     {
       value: 'gap-report.file',
       description:
-        'An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals.',
+        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
     },
 
     // template
     {
       value: 'template.list',
       description:
-        'Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.',
+        'The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.',
     },
     {
       value: 'template.show',
@@ -193,7 +219,7 @@ export const doc = {
     {
       value: 'theme.build',
       description:
-        'A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.',
+        'A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).',
     },
     {
       value: 'theme.build.check',
@@ -223,7 +249,7 @@ export const doc = {
     {
       value: 'theme.targets',
       description:
-        'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
+        'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.',
     },
     {
       value: 'theme.palette.generate',
@@ -237,6 +263,11 @@ export const doc = {
       description:
         'Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.',
     },
+    {
+      value: 'upgrade.registry',
+      description:
+        'The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.',
+    },
     {
       value: 'upgrade.status',
       description:
@@ -252,14 +283,27 @@ export const doc = {
     {
       value: 'manifest',
       description:
-        'The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.',
+        'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
+    },
+
+    // help and version, which no single command owns
+    {
+      value: 'help',
+      description:
+        'Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). ' +
+        "`--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). " +
+        'data.manifest marks the first shape; data.usage marks the second.',
+    },
+    {
+      value: 'version',
+      description: 'The CLI version, for `astryx --version --json`: {version}.',
     },
 
     // doctor
     {
       value: 'doctor',
       description:
-        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a `summary` of counts per status.',
+        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.',
     },
 
     // integration authoring
@@ -271,7 +315,7 @@ export const doc = {
     {
       value: 'integration.pack-check',
       description:
-        'The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues.',
+        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
     },
     {
       value: 'integration.validate',
@@ -281,7 +325,7 @@ export const doc = {
     {
       value: 'integration.template-conflicts',
       description:
-        'The integration identity, structural issues, and non-blocking conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command.',
+        'The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.',
     },
     {
       value: 'integration.component-conflicts',
@@ -291,7 +335,7 @@ export const doc = {
     {
       value: 'integration.doc-conflicts',
       description:
-        'The integration identity, structural issues, and Core doc overlaps classified as intentional replacements, intentional extensions, or accidental same-name conflicts.',
+        'The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
     },
 
     // layout (XLE/XLO)

package/foundation/response/response-types.doc.test.mjs

@@ -0,0 +1,181 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The response-types EnumDoc names every field of the responses below,
+ * nested entry fields included. Fields come from real responses where one is
+ * cheap to produce, else from the canonical typedef.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {describe, it, expect} from 'vitest';
+import {doc} from './response-types.doc.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+/** @param {string} type */
+const describedAs = (type) => doc.members.find((m) => m.value === type)?.description ?? '';
+
+/** @param {string} text @param {string} field */
+const names = (text, field) => new RegExp(`(^|\\W)${field}(\\W|$)`).test(text);
+
+/**
+ * Keys of an object, plus the keys of each nested object or array entry, `depth`
+ * levels down.
+ * @param {unknown} value @param {number} depth @returns {Set<string>}
+ */
+function fieldsOf(value, depth = 2) {
+  const out = new Set();
+  const visit = (/** @type {unknown} */ v, /** @type {number} */ d) => {
+    if (Array.isArray(v)) return v.forEach((item) => visit(item, d));
+    if (!v || typeof v !== 'object' || d < 0) return;
+    for (const [key, child] of Object.entries(v)) {
+      out.add(key);
+      visit(child, d - 1);
+    }
+  };
+  visit(value, depth);
+  return out;
+}
+
+/** @param {string[]} args @param {string} [cwd] */
+async function data(args, cwd) {
+  const {status, stdout} = await runCli(['--json', ...args], cwd ? {cwd} : undefined);
+  expect(status, stdout).toBe(0);
+  return JSON.parse(stdout);
+}
+
+/** @param {string} type @param {Iterable<string>} fields */
+function expectNamed(type, fields) {
+  const text = describedAs(type);
+  const missing = [...fields].filter((f) => !names(text, f));
+  expect(missing, `${type} omits`).toEqual([]);
+}
+
+describe('response-types EnumDoc names every field', () => {
+  it('component.batch names every row field and state', async () => {
+    const res = await data(['component', 'Button', 'Badge']);
+    expect(res.type).toBe('component.batch');
+    expect(describedAs('component.batch')).toMatch(/BatchResponse.*BatchRow/);
+    expectNamed('component.batch', [
+      'count',
+      'results',
+      'selector',
+      'status',
+      'result',
+      'code',
+      'error',
+      'candidates',
+      'package',
+      'component',
+      'kind',
+      'installed',
+      'suggestions',
+      'name',
+      'reason',
+    ]);
+  });
+
+  it('component.detail: the ownership fields and parentDoc', async () => {
+    const res = await data(['component', 'HStack']);
+    expect(res.type).toBe('component.detail');
+    const ownership = ['package', 'import', 'sourceAvailable', 'parentDoc'];
+    for (const f of ownership) expect(Object.keys(res.data)).toContain(f);
+    expectNamed('component.detail', ownership);
+    // The canonical response type declares parentDoc too.
+    const types = fs.readFileSync(
+      new URL('../../api/component/component.type.mjs', import.meta.url),
+      'utf8',
+    );
+    expect(types).toMatch(/@property \{string\} \[parentDoc\]/);
+  });
+
+  it('docs.index', async () => {
+    const res = await data(['docs', 'theme', '--index']);
+    expect(res.type).toBe('docs.index');
+    expectNamed('docs.index', fieldsOf(res.data));
+  });
+
+  it('search, across component, hook, template, and doc results', async () => {
+    const mixed = await data(['search', 'dashboard', '--limit', '50']);
+    const docsOnly = await data(['search', 'tokens', '--type', 'doc']);
+    expect(new Set(mixed.data.results.map((r) => r.domain))).toContain('template');
+    expectNamed('search', new Set([...fieldsOf(mixed.data), ...fieldsOf(docsOnly.data)]));
+  });
+
+  it('build.kit, including the hint a thin kit carries', async () => {
+    const res = await data(['build', 'zzqx-nothing-matches']);
+    expect(res.type).toBe('build.kit');
+    expect(res.data.hint).toBeDefined();
+    const fields = fieldsOf(res.data, 0);
+    for (const f of Object.keys(res.data.hint)) fields.add(f);
+    expectNamed('build.kit', fields);
+  });
+
+  it('theme.targets, including deprecatedFor', async () => {
+    const res = await data(['theme', 'targets']);
+    const fields = fieldsOf(res.data);
+    expect(fields).toContain('deprecatedFor');
+    expectNamed('theme.targets', fields);
+  });
+
+  it('gap-report.file, including each delivery', async () => {
+    const res = await data(['gap-report', 'Button', '--category', 'docs_gap', '--reason', 'probe']);
+    expect(res.type).toBe('gap-report.file');
+    expect(res.data.deliveries.length).toBeGreaterThan(0);
+    expectNamed('gap-report.file', fieldsOf(res.data));
+  });
+
+  it('theme.build, including notices', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-response-types-'));
+    fs.writeFileSync(path.join(cwd, 'package.json'), '{"name":"app","version":"1.0.0"}');
+    await data(['theme', 'template', 'starter.ts'], cwd);
+    const res = await data(['theme', 'build', 'starter.ts', '--out', 'starter.css'], cwd);
+    expect(res.type).toBe('theme.build');
+    expectNamed('theme.build', fieldsOf(res.data));
+  });
+
+  it('integration.pack-check (fields from api/integration/pack-check.type.mjs)', () => {
+    expectNamed('integration.pack-check', [
+      // PackCheckData
+      'name',
+      'version',
+      'packable',
+      'tarball',
+      'inventory',
+      'contributions',
+      'issues',
+      // PackCheckTarball
+      'filename',
+      'fileCount',
+      'size',
+      'unpackedSize',
+      // PackCheckInventory and PackCheckInventoryRoot
+      'manifest',
+      'roots',
+      'kind',
+      'path',
+      'expectedFiles',
+      'missingFiles',
+      'complete',
+      'packedFiles',
+      // contributions, each ContributionIdentities
+      'local',
+      'packed',
+      'themes',
+      'slug',
+      'exportName',
+      'components',
+      'templates',
+      'id',
+      'type',
+      'codemods',
+      'docs',
+      'agentDocsAppend',
+      // issues, each AstryxIntegrationIssue
+      'code',
+      'severity',
+      'message',
+    ]);
+  });
+});

package/foundation/response/response.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'schema',
   name: 'output',
   displayName: 'Output Envelope',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'The single JSON envelope every command emits under --json. Success is ' +
     '{ apiVersion, type, data, meta? }; failure is { apiVersion, error, code, ' +
@@ -39,16 +39,13 @@ export const doc = {
           name: 'type',
           type: 'string',
           description:
-            'Discriminator naming the payload shape. Each command guarantees ' +
-            'its own `type` at its return; there is no central union.',
+            'Names the payload shape. Every value is listed in the response-types enum.',
           required: true,
         },
         {
           name: 'data',
           type: 'unknown',
-          description:
-            "The command's payload. Structural by design, narrowed by the " +
-            'per-command return type, not by a map in the serializer.',
+          description: "The command's payload; its shape depends on `type`.",
           required: true,
         },
         {
@@ -64,7 +61,7 @@ export const doc = {
       type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
       description:
         'Emitted for every failure in --json mode, including uncaught throws ' +
-        'and Commander parse errors, which are converted to this shape.',
+        'and command-line parse errors, which are converted to this shape.',
       fields: [
         {
           name: 'apiVersion',
@@ -121,7 +118,7 @@ export const doc = {
       label: 'Success',
       code: `{
   "apiVersion": 1,
-  "type": "component",
+  "type": "component.detail",
   "data": { "name": "Button" }
 }`,
     },
@@ -153,9 +150,13 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'The process exit code is part of the contract too: successful commands ' +
-        'exit 0, and a JSON error envelope is accompanied by a non-zero exit ' +
-        '(jsonError exits 1).',
+        'The process exit code is part of the contract too. Exit 0 means success, ' +
+        'and every error envelope exits 1. Some commands also exit 1 with a success ' +
+        'envelope when what they report failed: a failed check (layout check, doctor ' +
+        'and its integration subcommands, integration verify, theme build ' +
+        '--check), a gap report that was not delivered, an upgrade left incomplete, ' +
+        'or init agent docs refused for a path outside the project. Read the ' +
+        'envelope, not the exit code, to tell them apart.',
     },
   ],
 };

package/foundation/text/string-utils.d.mts

@@ -40,4 +40,12 @@ export function searchComponents(needle: string, coreDir: string, components: Re
     score: number;
     reason: string;
 }[]>;
+/**
+ * The first sentence of a text, whitespace collapsed. A period after "e.g" or
+ * "i.e" does not end the sentence. Used where a description has to fit on one
+ * line: `build`'s alternatives and its text kit.
+ * @param {string} text
+ * @returns {string}
+ */
+export function firstSentence(text: string): string;
 export { levenshteinDistance } from "./levenshtein.mjs";

package/foundation/text/string-utils.mjs

@@ -56,7 +56,7 @@ export function findClosestComponents(name, components, maxDistance = 3) {
  * @returns {Promise<{name: string, score: number, reason: string}[]>}
  */
 export async function searchComponents(needle, coreDir, components) {
-  const {pathToFileURL} = await import('node:url');
+  const {readDocView} = await import('../doc-compiler/read.mjs');
   const fs = await import('node:fs');
   const path = await import('node:path');
 
@@ -100,8 +100,10 @@ export async function searchComponents(needle, coreDir, components) {
     // Levenshtein on name
     const dist = levenshteinDistance(term, compLower);
     if (dist === 1) addMatch(comp, 80, 'similar name (distance ' + dist + ')');
-    else if (dist === 2) addMatch(comp, 40, 'similar name (distance ' + dist + ')');
-    else if (dist === 3) addMatch(comp, 20, 'similar name (distance ' + dist + ')');
+    else if (dist === 2)
+      addMatch(comp, 40, 'similar name (distance ' + dist + ')');
+    else if (dist === 3)
+      addMatch(comp, 20, 'similar name (distance ' + dist + ')');
   }
 
   // --- Pass 2: Keyword + description matching (async, reads doc files) ---
@@ -124,15 +126,22 @@ export async function searchComponents(needle, coreDir, components) {
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         const nested = path.join(srcDir, entry.name, comp, comp + '.doc.mjs');
-        if (fs.existsSync(nested)) { docPath = nested; break; }
+        if (fs.existsSync(nested)) {
+          docPath = nested;
+          break;
+        }
       }
     }
 
     if (!docPath) continue;
 
     try {
-      const mod = await import(pathToFileURL(docPath).href);
-      const docs = mod.docs;
+      // Only the legacy `docs` export has ever been indexed here.
+      const docs = await readDocView(docPath, {
+        root: 'components',
+        loader: 'native',
+        exports: ['docs'],
+      });
       if (!docs) continue;
 
       // Keyword matching
@@ -157,8 +166,10 @@ export async function searchComponents(needle, coreDir, components) {
           }
 
           const dist = levenshteinDistance(term, kwLower);
-          if (dist === 1) addMatch(comp, 70, 'keyword "' + kw + '" (distance ' + dist + ')');
-          else if (dist === 2) addMatch(comp, 30, 'keyword "' + kw + '" (distance ' + dist + ')');
+          if (dist === 1)
+            addMatch(comp, 70, 'keyword "' + kw + '" (distance ' + dist + ')');
+          else if (dist === 2)
+            addMatch(comp, 30, 'keyword "' + kw + '" (distance ' + dist + ')');
         }
       }
 
@@ -191,8 +202,27 @@ export async function searchComponents(needle, coreDir, components) {
     }
   }
 
-  const results = Array.from(scored.values())
-    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  const results = Array.from(scored.values()).sort(
+    (a, b) => b.score - a.score || a.name.localeCompare(b.name),
+  );
 
   return results;
 }
+
+/**
+ * The first sentence of a text, whitespace collapsed. A period after "e.g" or
+ * "i.e" does not end the sentence. Used where a description has to fit on one
+ * line: `build`'s alternatives and its text kit.
+ * @param {string} text
+ * @returns {string}
+ */
+export function firstSentence(text) {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  const ends = /[.!?](?=\s|$)/g;
+  for (let m = ends.exec(flat); m; m = ends.exec(flat)) {
+    if (!/\b(e\.g|i\.e)$/i.test(flat.slice(0, m.index))) {
+      return flat.slice(0, m.index + 1);
+    }
+  }
+  return flat;
+}

package/foundation/xle/expand.d.mts

@@ -21,3 +21,5 @@ export function expand(doc: {
     states: number;
     todos: string[];
 };
+/** The most copies one `*N` repeat expands to. */
+export const MAX_REPEAT: 10000;

package/foundation/xle/expand.mjs

@@ -20,7 +20,8 @@ import {PAYLOAD_PROPS} from './validate.mjs';
 import {mergeImports, renderImport, prepareSpliceModule} from './splice.mjs';
 
 const INDENT = '  ';
-const MAX_REPEAT = 10000;
+/** The most copies one `*N` repeat expands to. */
+export const MAX_REPEAT = 10000;
 
 /** @param {string | null | undefined} text */
 function slugify(text) {
@@ -544,7 +545,7 @@ class Emitter {
       const flags = hint.flags.length > 0 ? ` (+${hint.flags.join(' +')})` : '';
       const arg = hint.arg ? `:${hint.arg}` : '';
       return [
-        `${pad}{/* TODO(xle): content block '${hint.block.name}'${flags}${arg} — scaffold it with: astryx template ${hint.block.name} */}`,
+        `${pad}{/* TODO(xle): content block '${hint.block.name}'${flags}${arg} — scaffold it with: astryx template ${hint.block.name} --type block */}`,
       ];
     }
     this.todos.push(`unresolved hint {${hint.name}}`);
@@ -642,7 +643,7 @@ class Emitter {
     /** @type {import('./xle-ast').XLENode[]} */
     const out = [];
     for (const item of items) {
-      const count = item.repeat || 1;
+      const count = Math.min(item.repeat || 1, MAX_REPEAT);
       for (let i = 1; i <= count; i++) {
         const clone = count > 1 ? cloneItem(item) : item;
         if (count > 1) {