@astryxdesign/cli 0.6.3-canary.7ada42e → 0.6.3-canary.7ec7be0

package/clients/cli/commands/build.mjs

@@ -4,8 +4,9 @@
  * @file build command — thin wrapper with a stable result summary.
  *
  *   astryx build                  → the PLAYBOOK (how to build a page)
- *   astryx build "<what>"         → a COMPOSITION KIT (closest page template,
- *                                   blocks, components) with a recommended START.
+ *   astryx build "<what>"         → the TEMPLATE to start from (always one: the
+ *                                   closest page, or the app shell), other
+ *                                   templates, then blocks and components.
  *
  * All grouping/scoring lives in api/build; this file only parses flags and
  * renders. Command strings are prefixed for the caller's package manager here
@@ -27,6 +28,7 @@ import {
   records,
 } from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
+import {firstSentence} from '../../../foundation/text/string-utils.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {build as buildApi} from '../../../api/build/build.mjs';
 import {doc as buildCommand} from './build.doc.mjs';
@@ -126,6 +128,7 @@ export function registerBuild(program) {
         hasResults,
         matchCount,
         directMatch,
+        start,
         pages,
         blocks,
         domain,
@@ -134,8 +137,8 @@ export function registerBuild(program) {
         hint,
       } = result.data;
       // The kit spans domains, so its kind comes from the pieces themselves.
-      // `frame` and `foundation` are always-on and deliberately excluded: they
-      // are not what the query matched.
+      // `start` (which may be the fallback shell), `frame` and `foundation`
+      // are deliberately excluded: they are not what the query matched.
       const answered = resultSetOf([...pages, ...blocks, ...domain], {
         count: matchCount,
         empty: !hasResults,
@@ -148,7 +151,7 @@ export function registerBuild(program) {
         return answered;
       }
 
-      if (!hasResults) {
+      if (!hasResults && !start) {
         emit(
           text(`No matches for "${q}".`),
           text(`Try a broader term, or browse: ${run} component --list`),
@@ -156,91 +159,126 @@ export function registerBuild(program) {
         return answered;
       }
 
-      // Same JSON->text projection as search, but leaner: the section header
-      // already says the kind, so drop `domain`/`import` by default (they're in
-      // --json and under --verbose). Keeps each item to name/displayName/desc/cmd.
-      const fields = options.verbose
-        ? [
-            'name',
-            'domain',
-            'displayName',
-            'score',
-            'reason',
-            'import',
-            'description',
-            'command',
-          ]
-        : ['name', 'displayName', 'description', 'command'];
+      // Four sections, one job each: the TEMPLATE to scaffold, OTHER
+      // TEMPLATES if its layout is wrong, BLOCKS for parts it lacks, and
+      // COMPONENTS for the rest. Descriptions stop at their first sentence and
+      // blocks and components share one command line in their heading; the
+      // JSON and --verbose carry everything.
+      const verbose = Boolean(options.verbose);
       /** @type {import('../formatters/index.mjs').RecordOptions} */
-      const recordOpts = {fields, format: {command: formatCliCommand}};
-
-      // `template <name> <path>` scaffolds into your project; <path> is the file
-      // (or folder) to write it to — a placeholder, since we can't know your
-      // layout. `--skeleton` and `component <Name>` just print, so no path.
-      const startCmd = directMatch
-        ? `${run} template ${pages[0].name} <path>`
-        : pages.length
-          ? `${run} template ${pages[0].name} --skeleton`
-          : `${run} component AppShell`;
-      const startNote = directMatch
-        ? `This \`${pages[0].name}\` page template appears to be the closest to what you want, so we recommend scaffolding it into your project — replace \`<path>\` with the file (or folder) to write it to — then adapting. Otherwise, browse PAGE TEMPLATES first, then BLOCKS and DOMAIN COMPONENTS below.`
-        : pages.length
-          ? `No exact match, but \`${pages[0].name}\` is the closest page template — run the above to print its layout as a reference, then compose. Otherwise, browse PAGE TEMPLATES first, then BLOCKS and DOMAIN COMPONENTS below.`
-          : 'No page template fits — frame with AppShell, then compose from BLOCKS and DOMAIN COMPONENTS below.';
-
-      // A short legend up top: what this output is, how to use it, and the exact
-      // order of the sections below (only the ones actually present) so it reads
-      // clearly and parses predictably.
-      const sectionsOrder = ['RECOMMENDED START'];
-      if (pages.length) sectionsOrder.push('PAGE TEMPLATES');
-      if (blocks.length) sectionsOrder.push('BLOCKS');
-      if (domain.length) sectionsOrder.push('DOMAIN COMPONENTS');
-      sectionsOrder.push('FRAME + FOUNDATION');
-      // The legend promises the complete order, so a section emitted after it
-      // has to be in it.
-      if (hint) sectionsOrder.push('FEW MATCHES');
+      const full = {
+        fields: [
+          'name',
+          'domain',
+          'displayName',
+          'score',
+          'reason',
+          'import',
+          'description',
+          'command',
+        ],
+        format: {command: formatCliCommand},
+      };
+      /** @param {string[]} fields */
+      const brief = fields => ({
+        fields,
+        format: {command: formatCliCommand, description: firstSentence},
+      });
+      // Blocks and components are extras: the text names the top few, and
+      // says how many more the JSON and --verbose carry.
+      const TOP = 3;
+      /** @param {unknown[]} items */
+      const shown = items => (verbose ? items : items.slice(0, TOP));
+      /** @param {unknown[]} items */
+      const more = items =>
+        !verbose && items.length > TOP
+          ? ` (top ${TOP} of ${items.length}; --verbose for all)`
+          : '';
 
       /** @type {import('../formatters/index.mjs').Block[]} */
       const out = [
         section(`Build kit for "${q}"`),
         text(
-          'A recommended set of pieces to assemble this page, in the order to use them. ' +
-            'Begin with RECOMMENDED START, then pull from the sections below — each ' +
-            'recommended item includes a `command:` to run next.\n' +
-            `Sections in order: ${sectionsOrder.join(', ')}.`,
+          start
+            ? 'Start from the TEMPLATE, fill it with BLOCKS, and use COMPONENTS only for what is left.\n' +
+                'Changing a page you already have? Keep it, and use only the blocks and components.'
+            : 'This kit is narrowed by --type, so it names no template.',
         ),
-        section('RECOMMENDED START', `${startNote}\n${startCmd}`),
       ];
 
-      if (pages.length) {
+      if (start) {
         out.push(
           section(
-            'PAGE TEMPLATES',
-            directMatch
-              ? 'Closest full-page templates — scaffold one, then adapt it.'
-              : 'Closest full-page templates — use as a layout reference.',
+            'TEMPLATE',
+            `${start.reason} ${
+              start.basis === 'fallback'
+                ? 'Scaffold it, then put blocks inside it.'
+                : 'Scaffold it, then replace its content. Keep its layout and spacing.'
+            }`,
+          ),
+          record(
+            start,
+            verbose
+              ? {
+                  fields: ['name', 'displayName', 'description', 'command'],
+                  format: {command: formatCliCommand},
+                }
+              : brief(['name', 'description', 'command']),
           ),
-          records(pages, recordOpts),
         );
+        if (start.alternatives.length) {
+          out.push(
+            section(
+              'OTHER TEMPLATES',
+              `If the layout is wrong, scaffold one of these instead. All page templates: ${formatCliCommand('template --list --type page')}`,
+            ),
+            records(
+              start.alternatives,
+              verbose ? full : brief(['name', 'description', 'command']),
+            ),
+          );
+        }
       }
-      if (blocks.length) {
+      // Search's own page matches, so the text carries every field the JSON
+      // does: one line by default, the full entries under --verbose.
+      if (pages.length) {
         out.push(
-          section('BLOCKS', 'Drop-in patterns that cover parts of the page.'),
-          records(blocks, recordOpts),
+          verbose
+            ? section(
+                'SEARCH MATCHES',
+                'Page templates keyword search matched, best first.',
+              )
+            : text(
+                `Keyword search matched these page templates: ${pages.map(p => p.name).join(', ')}.`,
+              ),
         );
+        if (verbose) out.push(records(pages, full));
       }
-      if (domain.length) {
+      if (blocks.length) {
         out.push(
-          section('DOMAIN COMPONENTS', 'Components specific to this idea.'),
-          records(domain, recordOpts),
+          section(
+            'BLOCKS',
+            `Ready-made sections for parts the template lacks${more(blocks)}. Print one: ${formatCliCommand('template <name>')}`,
+          ),
+          records(
+            shown(blocks),
+            verbose ? full : brief(['name', 'description']),
+          ),
         );
       }
-
       out.push(
         section(
-          'FRAME + FOUNDATION',
-          'Always-available shell + layout/text/action primitives.',
+          'COMPONENTS',
+          `For what the template and blocks do not cover${more(domain)}. Read one: ${formatCliCommand('component <name>')}`,
         ),
+        ...(domain.length
+          ? [
+              records(
+                shown(domain),
+                verbose ? full : brief(['name', 'description']),
+              ),
+            ]
+          : []),
         record({frame, foundation}),
       );
 

package/clients/cli/commands/build.text-fields.test.mjs

@@ -21,6 +21,8 @@ describe('build kit text fields mirror the JSON keys', () => {
     const {data} = JSON.parse(json.stdout);
     const keys = new Set([
       ...Object.keys(data),
+      ...Object.keys(data.start ?? {}),
+      ...(data.start?.alternatives ?? []).flatMap(a => Object.keys(a)),
       ...[...data.pages, ...data.blocks, ...data.domain].flatMap(e => Object.keys(e)),
     ]);
 
@@ -35,6 +37,45 @@ describe('build kit text fields mirror the JSON keys', () => {
       ),
     ];
     expect(fields).toContain('frame');
+    // The start is printed as a record, so its fields are checked too.
+    expect(fields).toContain('command');
+    expect(fields).toContain('displayName');
     for (const field of fields) expect(keys).toContain(field);
   }, SLOW);
+
+  it('leads with the start, then the alternatives, blocks and components', async () => {
+    const human = await runCli(['build', 'analytics dashboard'], REPO);
+    expect(human.status).toBe(0);
+    const headings = human.stdout
+      .split('\n')
+      .filter(line => /^(TEMPLATE|OTHER TEMPLATES|BLOCKS|COMPONENTS)$/.test(line));
+    expect(headings).toEqual(['TEMPLATE', 'OTHER TEMPLATES', 'BLOCKS', 'COMPONENTS']);
+    // A builder changing a page they already have keeps it.
+    expect(human.stdout).toContain(
+      'Changing a page you already have? Keep it, and use only the blocks and components.',
+    );
+  }, SLOW);
+
+  it("shortens the start's description by default and prints it whole under --verbose", async () => {
+    const json = await runCli(['build', 'quarterly revenue dashboard', '--json'], REPO);
+    const {start} = JSON.parse(json.stdout).data;
+    const first = start.description.slice(0, start.description.indexOf('. ') + 1);
+    expect(first.length).toBeGreaterThan(0);
+    expect(first.length).toBeLessThan(start.description.length);
+    const line = out => out.split('\n').find(l => l.startsWith('description:'));
+    const brief = await runCli(['build', 'quarterly revenue dashboard'], REPO);
+    expect(line(brief.stdout)).toBe(`description: ${first}`);
+    const whole = await runCli(['build', 'quarterly revenue dashboard', '--verbose'], REPO);
+    expect(whole.stdout).toContain(start.description);
+  }, SLOW);
+
+  it("names search's page matches in the default text", async () => {
+    const json = await runCli(['build', 'contact form', '--json'], REPO);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.pages.length).toBeGreaterThan(0);
+    const human = await runCli(['build', 'contact form'], REPO);
+    expect(human.stdout).toContain(
+      `Keyword search matched these page templates: ${data.pages.map(p => p.name).join(', ')}.`,
+    );
+  }, SLOW);
 });

package/clients/cli/commands/component/index.mjs

@@ -111,7 +111,7 @@ export function registerComponent(program) {
       // doctor integration validate. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }

package/clients/cli/commands/component-ownership.test.mjs

@@ -71,7 +71,7 @@ function createFixture({
   );
   fs.writeFileSync(
     path.join(compDir, 'MetaAppShell.doc.mjs'),
-    `export const docs = {\n  name: 'MetaAppShell',\n  usage: { description: 'Meta-flavored app shell.' },\n  props: [{ name: 'title', type: 'string', description: 'Header title' }],\n};\n`,
+    `export default {\n  type: 'component',\n  name: 'MetaAppShell',\n  usage: { description: 'Meta-flavored app shell.' },\n  props: [{ name: 'title', type: 'string', description: 'Header title' }],\n};\n`,
   );
   if (withSource) {
     fs.writeFileSync(
@@ -82,7 +82,7 @@ function createFixture({
   if (extraComponent) {
     fs.writeFileSync(
       path.join(compDir, `${extraComponent}.doc.mjs`),
-      `export const docs = {\n  name: '${extraComponent}',\n  usage: { description: '${extraComponent} from meta.' },\n};\n`,
+      `export default {\n  type: 'component',\n  name: '${extraComponent}',\n  usage: { description: '${extraComponent} from meta.' },\n  props: [],\n};\n`,
     );
     fs.writeFileSync(
       path.join(compDir, `${extraComponent}.tsx`),
@@ -100,7 +100,7 @@ function createFixture({
       : '';
     fs.writeFileSync(
       path.join(entryDir, `${entryPoint.component}.doc.mjs`),
-      `export const docs = {\n  name: '${entryPoint.component}',${ownSpecifier}\n  usage: { description: '${entryPoint.component} from an entry point.' },\n};\n`,
+      `export default {\n  type: 'component',\n  name: '${entryPoint.component}',${ownSpecifier}\n  usage: { description: '${entryPoint.component} from an entry point.' },\n  props: [],\n};\n`,
     );
   }
 

package/clients/cli/commands/discover.broken-integration.test.mjs

@@ -69,11 +69,12 @@ describe('astryx discover with a manifest that fails to load', () => {
 
     expect(status).toBe(0);
     expect(stderr).toContain(
-      'Warning: @test/broken has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @test/broken',
+      'Warning: @test/broken has 1 integration issue(s). Run: astryx doctor',
     );
     expect(stdout).not.toContain('No integrations configured.');
-    expect(stdout).toContain('No external components found in configured integrations.');
+    expect(stdout).toContain(
+      'No external components found in configured integrations.',
+    );
   });
 
   it('reports meta.configured=true in --json, with the nudge suppressed', async () => {
@@ -101,7 +102,7 @@ describe('astryx discover with a configured package that is not installed', () =
     );
     fs.writeFileSync(
       path.join(healthy, 'components', 'Widget.doc.mjs'),
-      `export const docs = {name: 'Widget', usage: {description: 'A widget.'}};\n`,
+      `export const docs = {name: 'Widget', usage: {description: 'A widget.'}, props: []};\n`,
     );
     fs.writeFileSync(
       path.join(healthy, 'components', 'Widget.tsx'),
@@ -129,8 +130,7 @@ describe('astryx discover with a configured package that is not installed', () =
 
     expect(status).toBe(0);
     expect(stderr).toContain(
-      'Warning: @test/missing has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @test/missing',
+      'Warning: @test/missing has 1 integration issue(s). Run: astryx doctor\n',
     );
   });
 });
@@ -149,8 +149,7 @@ describe('astryx search with a manifest that fails to load', () => {
 
     expect(status).toBe(0);
     expect(stderr).toContain(
-      'Warning: @test/broken has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @test/broken',
+      'Warning: @test/broken has 1 integration issue(s). Run: astryx doctor',
     );
 
     const asJson = await runCli(['search', 'button', '--json'], {cwd: project});

package/clients/cli/commands/discover.mjs

@@ -83,7 +83,7 @@ export function registerDiscover(program) {
       // doctor integration validate. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }

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

@@ -15,10 +15,14 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Print reference docs',
   description:
-    'Reads the reference docs: with no topic it lists every topic; a topic prints that ' +
-    '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).',
+    'Reads the reference docs one level at a time: with no topic it lists every topic; a ' +
+    'topic lists its sections, each with the key to read it by (a topic with one section ' +
+    'prints whole); a topic plus a section prints that section; `--full` prints the whole ' +
+    'topic, as does `--dense`. With `--json`, a topic returns its whole doc, as docs() ' +
+    'does, and `--index` its section index. A route ' +
+    'opens a node of the docs tree: `cli` lists its guides and reference, ' +
+    '`cli/api/functions` lists every API function, and `cli/api/functions/search` prints ' +
+    'one.',
   fn: 'docs',
   args: [
     {name: 'topic', param: 'topic', required: false},
@@ -28,20 +32,28 @@ export const doc = {
     {
       flag: '--index',
       param: 'options.index',
-      description: "List the topic's sections and their keys instead of printing the whole topic",
+      description: "List the topic's sections and their keys, even for a topic with one section",
+    },
+    {
+      flag: '--full',
+      description:
+        'Print the whole topic instead of its sections (text; `--json` returns the whole topic unless --index). Cannot be set with --index',
     },
   ],
   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: "A topic's sections", cli: 'astryx docs theme'},
+    {label: 'A whole topic as JSON', cli: 'astryx docs spacing --json'},
     {label: 'One section', cli: 'astryx docs theme quick-start'},
+    {label: 'The CLI docs tree', cli: 'astryx docs cli'},
+    {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
+    {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown topic, or a section that matches no section or more than one',
+      when: 'unknown topic or route, or a section that matches no section or more than one',
     },
   ],
   related: ['search', 'component', 'hook', 'template'],