@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

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
@@ -22,57 +23,45 @@ import {
   emit,
   section,
   text,
+  list,
   record,
   records,
-  ARROW,
 } 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';
 import {doc as buildFn} from '../../../api/build/build.doc.mjs';
 
 /**
- * Emit the build playbook (shown when `build` is run with no query).
- * @param {string} run - The CLI invocation prefix (e.g. `npx astryx`).
+ * Playbook commands as records whose field names are the JSON keys, so a
+ * reader can grep `^command:`. The command is run with the caller's invocation.
+ * @type {import('../formatters/index.mjs').RecordOptions}
  */
-function printPlaybook(run) {
+const COMMAND_RECORDS = {
+  fields: ['command', 'purpose'],
+  format: {command: command => formatCliCommand(command)},
+};
+
+/**
+ * Emit the build playbook (shown when `build` is run with no query) — a
+ * projection of the `build.help` data, so text and JSON carry the same steps.
+ * @param {import('../../../api/build/build.type.mjs').BuildHelpResponse['data']} playbook
+ */
+function printPlaybook(playbook) {
   emit(
-    section('How to build a page with Astryx'),
-    text(
-      [
-        "1. Find a starting point for what you're building:",
-        `     ${run} build "<what you're building>"`,
-        `   ${ARROW} returns the closest [page] template, the [block]s that cover parts,`,
-        '     and the [component]s to fill the gaps, with a "Compose:" suggestion.',
-      ].join('\n'),
-    ),
-    text(
-      [
-        `2. If a [page] template matches ${ARROW} scaffold it and adapt:`,
-        `     ${run} template <name> [path]`,
-      ].join('\n'),
-    ),
-    text(
-      [
-        `3. If nothing matches exactly ${ARROW} compose:`,
-        `     ${run} template <name> --skeleton   # study a close page's layout`,
-        `     ${run} template <BlockName>         # drop in each block from the kit`,
-        `     ${run} component <Name>             # fill remaining gaps (read props)`,
-      ].join('\n'),
-    ),
-    text(
-      [
-        '4. Rules (keep it on-system):',
-        '   - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
-        `   - No style={{}} — use component props; design tokens via \`${run} docs tokens\`.`,
-        '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
-      ].join('\n'),
-    ),
-    text(
-      `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral ` +
-        `lookup of any component/doc/template, use \`${run} search <query>\`.`,
-    ),
+    section(playbook.title),
+    ...playbook.steps.flatMap((step, i) => [
+      section(`${i + 1}. ${step.title}`),
+      records(step.commands, COMMAND_RECORDS),
+      step.returns ? record({returns: step.returns}) : null,
+    ]),
+    section(`${playbook.steps.length + 1}. Rules (keep it on-system)`),
+    list(playbook.rules),
+    ...(playbook.related.length > 0
+      ? [section('Related'), records(playbook.related, COMMAND_RECORDS)]
+      : []),
   );
 }
 
@@ -91,7 +80,10 @@ export function registerBuild(program) {
 
       // No query → the playbook. Still routed through the API for the envelope.
       if (!query || !String(query).trim()) {
-        const result = await buildApi(undefined, {cwd: process.cwd()});
+        const result =
+          /** @type {import('../../../api/build/build.type.mjs').BuildHelpResponse} */ (
+            await buildApi(undefined, {cwd: process.cwd()})
+          );
         // The playbook is a document, not a lookup: one doc, always the same
         // one. Counting it as a result keeps "what did this run answer with"
         // true for the no-argument form too.
@@ -100,7 +92,7 @@ export function registerBuild(program) {
           jsonOut(result);
           return playbook;
         }
-        printPlaybook(run);
+        printPlaybook(result.data);
         return playbook;
       }
 
@@ -136,6 +128,7 @@ export function registerBuild(program) {
         hasResults,
         matchCount,
         directMatch,
+        start,
         pages,
         blocks,
         domain,
@@ -144,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,
@@ -158,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`),
@@ -166,97 +159,127 @@ 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>')}`,
         ),
-        record({
-          frame,
-          foundation,
-          setup:
-            'import "@astryxdesign/core/reset.css" + "astryx.css"; no <div>/style for layout — use Stack/Grid + tokens',
-        }),
+        ...(domain.length
+          ? [
+              records(
+                shown(domain),
+                verbose ? full : brief(['name', 'description']),
+              ),
+            ]
+          : []),
+        record({frame, foundation}),
       );
 
       // Last, so it is the line the reader leaves with — and only when the kit

package/clients/cli/commands/build.playbook.test.mjs

@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The no-query `build` playbook is data. `--json` carries every step,
+ * rule and command; the text output is rendered from those values and shows
+ * nothing the envelope lacks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {program} from '../index.mjs';
+
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const SLOW = 30_000;
+
+/** @param {string} s */
+const ascii = s => s.replace(/[\u2014\u2013]/g, '-');
+
+describe('build playbook: text is a projection of the JSON', () => {
+  it('prints exactly the commands, steps and rules the envelope carries', async () => {
+    const json = await runCli(['build', '--json'], REPO);
+    expect(json.status).toBe(0);
+    const {type, data} = JSON.parse(json.stdout);
+    expect(type).toBe('build.help');
+    expect(data.steps.length).toBeGreaterThan(0);
+    expect(data.rules.length).toBeGreaterThan(0);
+
+    const human = await runCli(['build'], REPO);
+    expect(human.status).toBe(0);
+    const out = human.stdout;
+
+    expect(out).toContain(ascii(data.title));
+    for (const step of data.steps) {
+      expect(out).toContain(ascii(step.title));
+      if (step.returns) expect(out).toContain(ascii(step.returns));
+    }
+    for (const rule of data.rules) expect(out).toContain(ascii(rule));
+
+    /** @type {Array<{command: string, purpose?: string}>} */
+    const commands = [
+      ...data.steps.flatMap((/** @type {any} */ s) => s.commands),
+      ...data.related,
+    ];
+    // Each command is one record whose field names are the JSON keys:
+    // `command:` (run with the caller's invocation), then `purpose:`.
+    const printed = out
+      .split('\n')
+      .filter(line => line.startsWith('command: '))
+      .map(line => line.slice('command: '.length).trim());
+    expect(printed).toHaveLength(commands.length);
+    commands.forEach(({command, purpose}, i) => {
+      expect(printed[i].endsWith(` ${command}`)).toBe(true);
+      if (purpose) expect(out).toContain(`purpose: ${ascii(purpose)}`);
+    });
+    // No column the handler drew itself.
+    expect(out).not.toMatch(/ {2,}# /);
+  }, SLOW);
+
+  it('names only commands this CLI registers', async () => {
+    const {stdout} = await runCli(['build', '--json'], REPO);
+    const {data} = JSON.parse(stdout);
+    const registered = new Set(program.commands.map(c => c.name()));
+    const commands = [
+      ...data.steps.flatMap((/** @type {any} */ s) => s.commands),
+      ...data.related,
+    ];
+    expect(commands.length).toBeGreaterThan(0);
+    for (const {command} of commands) {
+      expect(registered.has(command.split(' ')[0])).toBe(true);
+    }
+  }, SLOW);
+});

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

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `build "<idea>"` text output names only fields the `build.kit`
+ * envelope carries — on the kit itself or on its entries.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const SLOW = 60_000;
+
+describe('build kit text fields mirror the JSON keys', () => {
+  it('prints no field the envelope lacks', async () => {
+    const json = await runCli(['build', 'analytics dashboard', '--json', '--verbose'], REPO);
+    expect(json.status).toBe(0);
+    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)),
+    ]);
+
+    const human = await runCli(['build', 'analytics dashboard', '--verbose'], REPO);
+    expect(human.status).toBe(0);
+    const fields = [
+      ...new Set(
+        human.stdout
+          .split('\n')
+          .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
+          .filter(Boolean),
+      ),
+    ];
+    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

@@ -26,7 +26,6 @@ import {defineCommand} from '../../lib/define-command.mjs';
 import {resultSet} from '../../../../foundation/debug/index.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
 import {component as componentApi} from '../../../../api/component/component.mjs';
-import {findRelatedBlocks} from '../../../../api/template/template.mjs';
 import {Project} from '../../../../foundation/config/project.mjs';
 import {warnOnIntegrationIssues} from '../../../../foundation/integrations/integration-warnings.mjs';
 import {doc as componentCommand} from '../component.doc.mjs';
@@ -112,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.
       }
@@ -235,18 +234,14 @@ export function registerComponent(program) {
         case 'component.detail': {
           const resolvedName = (name || '').replace(/^XDS/, '');
           const importHint = result.data.import;
+          if (result.data.parentDoc) emit(record(result.data, {fields: ['parentDoc']}));
           const doc =
             detail === 'brief'
               ? code(formatBrief(result.data, resolvedName, importHint, {themeData}))
               : detail === 'compact'
                 ? code(formatCompact(result.data, resolvedName, importHint))
                 : code(formatFull(result.data, {themeData, importHint}));
-          const related = await findRelatedBlocks(resolvedName);
-          emit(
-            doc,
-            related.length > 0 && section('Related block templates'),
-            related.length > 0 && records(related, {fields: ['dirName', 'description']}),
-          );
+          emit(doc);
           break;
         }
 

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/component-package.test.mjs

@@ -5,6 +5,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {component} from '../../../api/component/component.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
 
 // These tests create a minimal monorepo fixture with:
 // - packages/core (symlinked to real @astryxdesign/core for loadDocs compatibility)
@@ -120,4 +121,49 @@ describe('component() with --package option', () => {
     expect(result.data.source).toContain('ProfileCardShowcase');
     expect(result.data.aspectRatio).toBeCloseTo(16 / 9);
   });
+
+  // A legacy package ships docs only: --source and --blocks answer the same
+  // way scoped as unscoped, never falling back to the plain doc.
+  it('--package + --source reports the missing source, like the unscoped lookup', async () => {
+    await expect(
+      component('ProfileCard', {cwd: tmpDir, source: true}),
+    ).rejects.toMatchObject({code: 'ERR_NO_SOURCE'});
+    await expect(
+      component('ProfileCard', {cwd: tmpDir, package: '@test/ext', source: true}),
+    ).rejects.toMatchObject({code: 'ERR_NO_SOURCE'});
+  });
+
+  it('--package + --blocks returns the blocks, like the unscoped lookup', async () => {
+    const unscoped = await component('ProfileCard', {cwd: tmpDir, blocks: true});
+    const scoped = await component('ProfileCard', {cwd: tmpDir, package: '@test/ext', blocks: true});
+    expect(scoped.type).toBe('component.detail.blocks');
+    expect(scoped.data).toEqual(unscoped.data);
+  });
+
+  // `cwd` is an explicit API input: --blocks must discover from it, as
+  // --showcase does, not from the process working directory.
+  it('--blocks discovers blocks from options.cwd, like --showcase', async () => {
+    const showcase = await component('ProfileCard', {cwd: tmpDir, showcase: true});
+    expect(showcase.data.source).toContain('ProfileCardShowcase');
+
+    const blocks = await component('ProfileCard', {cwd: tmpDir, blocks: true});
+    expect(blocks.type).toBe('component.detail.blocks');
+    expect(blocks.data.showcase?.name).toBe('ProfileCardShowcase');
+  });
+
+  // List and detail report one import for a legacy package component; the
+  // text list projects the JSON value instead of deriving a Core path.
+  it('the names list gives a legacy package component the import its detail reports', async () => {
+    const detail = await component('ProfileCard', {cwd: tmpDir});
+    const list = await component(undefined, {cwd: tmpDir, list: true});
+    const entry = Object.values(list.data.components)
+      .flat()
+      .find(e => e.name === 'ProfileCard' && e.package === '@test/ext');
+    expect(entry?.import).toBe(detail.data.import);
+
+    const text = await runCli(['component', '--list'], tmpDir);
+    expect(text.code).toBe(0);
+    expect(text.stdout).toContain(`name:   ProfileCard\nimport: ${detail.data.import}  [@test/ext]`);
+    expect(text.stdout).not.toMatch(/^import: +@astryxdesign\/core\S* +\[@test\/ext\]$/m);
+  });
 });