@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.dea6813

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

@@ -87,6 +87,54 @@ describe('astryx discover with a manifest that fails to load', () => {
   });
 });
 
+describe('astryx discover with a configured package that is not installed', () => {
+  beforeEach(() => {
+    const healthy = path.join(project, 'node_modules', '@test', 'healthy');
+    fs.mkdirSync(path.join(healthy, 'components'), {recursive: true});
+    fs.writeFileSync(
+      path.join(healthy, 'package.json'),
+      JSON.stringify({name: '@test/healthy', version: '2.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(healthy, 'astryx.integration.mjs'),
+      `export default {components: './components'};\n`,
+    );
+    fs.writeFileSync(
+      path.join(healthy, 'components', 'Widget.doc.mjs'),
+      `export const docs = {name: 'Widget', usage: {description: 'A widget.'}};\n`,
+    );
+    fs.writeFileSync(
+      path.join(healthy, 'components', 'Widget.tsx'),
+      `export function Widget() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(project, 'astryx.config.mjs'),
+      `export default {integrations: ['@test/missing', '@test/healthy']};\n`,
+    );
+  });
+
+  it('still lists the healthy package and exits 0', async () => {
+    const {status, stdout} = await runCli(['discover', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).data).toEqual([
+      expect.objectContaining({name: '@test/healthy', components: ['Widget']}),
+    ]);
+  });
+
+  it('names the missing package in the stderr nudge', async () => {
+    const {status, stderr} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expect(stderr).toContain(
+      'Warning: @test/missing has 1 integration issue(s). ' +
+        'Run: astryx doctor integration validate @test/missing',
+    );
+  });
+});
+
 describe('astryx search with a manifest that fails to load', () => {
   // search needs a resolvable @astryxdesign/core; without one it errors out
   // before it can list anything, which is not the case under test.

package/clients/cli/commands/discover.components-flag.test.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover --components` does what its doc says.
+ *
+ * The flag only lifts the package list's component summary (the first 10
+ * names plus "+N more") so every component prints. It changes nothing in
+ * `--json`, whose entries always carry the full array.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc} from './discover.doc.mjs';
+import {doc as discoverFn} from '../../../api/discover/discover.doc.mjs';
+
+const NAMES = Array.from({length: 12}, (_, i) => `Part${String(i).padStart(2, '0')}`);
+
+let tmpDir;
+let project;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-components-'));
+  project = path.join(tmpDir, 'project');
+  const pkgDir = path.join(project, 'node_modules', '@test', 'kit');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({name: 'proj', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(project, 'astryx.config.mjs'),
+    `export default {integrations: ['@test/kit']};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@test/kit', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  for (const name of NAMES) {
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.doc.mjs`),
+      `export const docs = {name: '${name}', usage: {description: 'A part.'}};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.tsx`),
+      `export function ${name}() { return null; }\n`,
+    );
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} stdout */
+function componentsLine(stdout) {
+  return stdout.split('\n').find(line => line.startsWith('components:'));
+}
+
+describe('astryx discover --components', () => {
+  it('lists every component where the default list shows the first 10', async () => {
+    const summary = await runCli(['discover'], {cwd: project});
+    const full = await runCli(['discover', '--components'], {cwd: project});
+
+    expect(componentsLine(summary.stdout)).toMatch(
+      new RegExp(`${NAMES[9]}, \\+2 more$`),
+    );
+    expect(componentsLine(full.stdout)).toMatch(new RegExp(`${NAMES.join(', ')}$`));
+  });
+
+  it('leaves the --json response unchanged', async () => {
+    const plain = await runCli(['discover', '--json'], {cwd: project});
+    const flagged = await runCli(['discover', '--components', '--json'], {
+      cwd: project,
+    });
+
+    expect(JSON.parse(flagged.stdout)).toEqual(JSON.parse(plain.stdout));
+  });
+
+  it('is documented as that behavior, with an example', () => {
+    const option = doc.options?.find(o => o.flag === '--components');
+    const param = discoverFn.params?.find(p => p.name === 'options.components');
+
+    for (const description of [option?.description, param?.description]) {
+      expect(description).toMatch(/every component/i);
+      expect(description).toMatch(/first 10/);
+      expect(description).not.toMatch(/components only/i);
+    }
+    expect(doc.examples?.some(e => /\s--components\b/.test(e.cli))).toBe(true);
+  });
+});

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

@@ -25,18 +25,20 @@ export const doc = {
     {
       flag: '--components',
       param: 'options.components',
-      description: 'List components only',
+      description:
+        'In the package list, print every component of each package instead of the first 10 and a "+N more" count. No effect on --json output or on a package, component, or search query.',
     },
   ],
   examples: [
     {label: 'List packages', cli: 'astryx discover --json'},
+    {label: 'List every component of each package', cli: 'astryx discover --components'},
     {label: 'Browse a package', cli: 'astryx discover @acme/ui'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown package or component, a malformed doc, or an empty free-text query',
+      when: 'unknown package or component, a malformed doc, or a blank query when packages are discovered',
     },
   ],
   related: ['component', 'search', 'template'],

package/clients/cli/commands/discover.mjs

@@ -122,11 +122,11 @@ export function registerDiscover(program) {
             break;
           }
 
-          // One record per package — fields mirror the JSON entry. The default
+          // One record per package, every field of the JSON entry. The default
           // view summarizes each package's components (first N + "+N more");
           // --components lists them all (record comma-joins the full array).
           /** @type {import('../formatters/index.mjs').RecordOptions} */
-          const listOpts = {fields: ['displayName', 'name', 'description', 'components']};
+          const listOpts = {};
           if (!options.components) {
             listOpts.format = {
               components: (/** @type {string[]} */ comps) => {
@@ -155,7 +155,7 @@ export function registerDiscover(program) {
         case 'discover.detail': {
           const d = result.data;
           emit(
-            record(d, {fields: ['displayName', 'name', 'description', 'components']}),
+            record(d),
             text(`Usage: ${run} discover ${d.name}/<ComponentName>`),
           );
           break;

package/clients/cli/commands/discover.text-projection.test.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` text output projects every field of its JSON entry.
+ *
+ * The text views of `discover.list` and `discover.detail` are renderings of the
+ * same entries `--json` returns, so each entry key must appear as a `key:` line
+ * carrying the same value.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+let tmpDir;
+let project;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-text-'));
+  project = path.join(tmpDir, 'project');
+  const pkgDir = path.join(project, 'node_modules', '@test', 'kit');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({name: 'proj', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(project, 'astryx.config.mjs'),
+    `export default {integrations: ['@test/kit']};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@test/kit', version: '3.1.4'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  for (const name of ['Dial', 'Gauge']) {
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.doc.mjs`),
+      `export const docs = {name: '${name}', usage: {description: 'A ${name}.'}};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.tsx`),
+      `export function ${name}() { return null; }\n`,
+    );
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * @param {Record<string, unknown>} entry
+ * @param {string} text
+ */
+function expectEveryField(entry, text) {
+  const lines = text.split('\n');
+  for (const [key, value] of Object.entries(entry)) {
+    const rendered = Array.isArray(value) ? value.join(', ') : String(value);
+    expect(lines).toContainEqual(
+      expect.stringMatching(new RegExp(`^${key}:\\s+${escape(rendered)}$`)),
+    );
+  }
+}
+
+/** @param {string} s */
+function escape(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+describe('astryx discover text output', () => {
+  it('lists every field of each discover.list entry', async () => {
+    const asJson = await runCli(['discover', '--json'], {cwd: project});
+    const [entry] = JSON.parse(asJson.stdout).data;
+    expect(Object.keys(entry)).toEqual(
+      expect.arrayContaining(['name', 'category', 'components', 'version']),
+    );
+
+    const {status, stdout} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expectEveryField(entry, stdout);
+  });
+
+  it('shows every field of the discover.detail entry', async () => {
+    const asJson = await runCli(['discover', '@test/kit', '--json'], {
+      cwd: project,
+    });
+    const {data} = JSON.parse(asJson.stdout);
+
+    const {status, stdout} = await runCli(['discover', '@test/kit'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expectEveryField(data, stdout);
+  });
+});

package/clients/cli/commands/doctor-integration.package-json.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {validateIntegration} from '../../../api/integration/validate-integration.mjs';
+
+const NO_MANIFEST = 'No astryx.integration.* found next to package.json.';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-pkgjson-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "@acme/widgets",}\n');
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {\n  templates: './templates',\n};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('doctor integration with a malformed package.json', () => {
+  it('keeps a null name for the no-manifest case only', async () => {
+    const result = await validateIntegration(undefined, {cwd: tmpDir});
+
+    expect(result.data.name).toBe('(local package)');
+    expect(result.data.issues.map(issue => issue.code)).toEqual([
+      'invalid_package_json',
+    ]);
+  });
+
+  for (const leaf of ['validate', 'templates', 'components', 'docs']) {
+    it(`${leaf} prints the package.json error instead of "no manifest"`, async () => {
+      const text = await runCli(['doctor', 'integration', leaf], tmpDir);
+      const json = await runCli(
+        ['doctor', 'integration', leaf, '--json'],
+        tmpDir,
+      );
+
+      expect(text.status).toBe(1);
+      expect(json.status).toBe(1);
+      expect(text.stdout).not.toContain(NO_MANIFEST);
+      expect(text.stdout).toContain('invalid_package_json');
+      expect(JSON.parse(json.stdout).data.issues).toContainEqual(
+        expect.objectContaining({code: 'invalid_package_json'}),
+      );
+    });
+  }
+});

package/clients/cli/commands/doctor.mjs

@@ -17,7 +17,7 @@ import {
   validateIntegration,
 } from '../../../api/integration/validate-integration.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, records, text} from '../formatters/index.mjs';
+import {emit, section, record, records, text} from '../formatters/index.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as doctorCommand} from './doctor.doc.mjs';
 import {doc as doctorIntegrationGroup} from './doctor-integration.doc.mjs';
@@ -55,7 +55,7 @@ function integrationLabel(data) {
  * @param {import('../../../api/doctor/doctor.mjs').DoctorReport} report
  */
 function printHuman(report) {
-  const {pass, warn, fail, info} = report.summary;
+  const {warn, fail} = report.summary;
   const closing =
     fail > 0
       ? 'Some checks failed. Address the items marked [fail] above.'
@@ -63,18 +63,15 @@ function printHuman(report) {
         ? 'No failures — but review the [warn] warnings above when you can.'
         : 'All checks passed. Your Astryx setup looks healthy.';
 
+  // Field names are the JSON keys, so text and --json map one to one.
   emit(
     section('astryx doctor — diagnosing your setup'),
     records(report.checks, {
-      fields: ['status', 'label', 'message', 'fix'],
-      labels: {label: 'check'},
+      fields: ['id', 'status', 'label', 'message', 'fix'],
       format: {status: statusToken},
     }),
-    text(
-      `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
-        `${fail} failure${fail === 1 ? '' : 's'}` +
-        (info ? `, ${info} info` : ''),
-    ),
+    section('summary'),
+    record(report.summary, {fields: ['pass', 'warn', 'fail', 'info']}),
     text(closing),
   );
 }
@@ -290,13 +287,6 @@ export function registerDoctor(program) {
     fn: doctorFn,
     action: async () => runProjectDoctor(program),
   });
-  doctorCmd.addHelpText(
-    'after',
-    '\nExit code:\n' +
-      '  0  no failures (warnings are allowed) — safe as a CI gate\n' +
-      '  1  one or more checks failed\n',
-  );
-
   /** @type {import('commander').Command} */
   let integrationCmd;
   integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {

package/clients/cli/commands/doctor.test.mjs

@@ -354,3 +354,45 @@ describe('doctor — command', () => {
     }
   });
 });
+
+describe('doctor — text output mirrors the JSON', () => {
+  /** @param {string} line */
+  const field = line => /^(\w+):\s+(.*)$/.exec(line)?.slice(1) ?? [line, ''];
+
+  it('prints every check and summary field under its JSON key', async () => {
+    const prevCwd = process.cwd();
+    const prevExit = process.exitCode;
+    process.chdir(tmpDir);
+    try {
+      await createProgram().parseAsync(['node', 'astryx', '--json', 'doctor']);
+      const {checks, summary} = JSON.parse(logCalls.join('\n')).data;
+      logCalls = [];
+      await createProgram().parseAsync(['node', 'astryx', 'doctor']);
+      const blocks = logCalls
+        .join('\n')
+        .split(/\n{2,}/)
+        .map(block => block.split('\n').map(field));
+
+      for (const check of checks) {
+        const block = blocks.find(fields =>
+          fields.some(([key, value]) => key === 'id' && value === check.id),
+        );
+        expect(block, `no text record for check ${check.id}`).toBeDefined();
+        expect(
+          /** @type {string[][]} */ (block).map(([key]) => key).sort(),
+        ).toEqual(Object.keys(check).sort());
+      }
+
+      const heading = blocks.findIndex(
+        fields => fields.length === 1 && fields[0][0] === 'summary',
+      );
+      expect(heading, 'no summary section').toBeGreaterThan(-1);
+      expect(blocks[heading + 1]).toEqual(
+        Object.entries(summary).map(([key, count]) => [key, String(count)]),
+      );
+    } finally {
+      process.chdir(prevCwd);
+      process.exitCode = prevExit;
+    }
+  }, 60_000);
+});

package/clients/cli/commands/gap-report.doc.mjs

@@ -15,22 +15,32 @@ export const doc = {
   description:
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',
   fn: 'gapReport',
-  args: [{name: 'component', param: 'component', required: false}],
+  args: [
+    {
+      name: 'component',
+      param: 'component',
+      required: false,
+      description:
+        'Component or design-system area the gap is about, up to 120 characters. Required unless --list-categories is set.',
+    },
+  ],
   options: [
     {
       flag: '--category <category>',
       param: 'options.category',
-      description: 'Gap category (run --list-categories for values)',
+      description:
+        'Gap category (run --list-categories for values). Required unless --list-categories is set.',
     },
     {
       flag: '--reason <reason>',
       param: 'options.reason',
-      description: 'What capability was missing or difficult',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless --list-categories is set.',
     },
     {
       flag: '--additional-context <text>',
       param: 'options.detail',
-      description: 'Optional additional context',
+      description: 'Optional additional context, up to 8000 characters',
     },
     {
       flag: '--package <pkg>',
@@ -45,7 +55,8 @@ export const doc = {
     {
       flag: '--list-categories',
       param: 'options.listCategories',
-      description: 'List valid report categories without filing',
+      description:
+        'List valid report categories without filing; the component and the other gap-report options are ignored',
     },
   ],
   examples: [

package/clients/cli/commands/gap-report.test.mjs

@@ -196,3 +196,75 @@ export default {};\n`,
     });
   });
 });
+
+describe('gap-report control docs', () => {
+  const REQUIRED = 'Required unless --list-categories is set.';
+
+  it('help and manifest say which inputs are required and how long they may be', async () => {
+    const help = await runCli(['gap-report', '--help']);
+    expect(help.status).toBe(0);
+    const manifest = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const entry = manifest.data.commands.find(
+      (/** @type {{name: string}} */ command) => command.name === 'gap-report',
+    );
+    /** @param {string} flag @returns {string} */
+    const option = flag =>
+      entry.options.find(
+        (/** @type {{flag: string}} */ item) => item.flag.split(' ')[0] === flag,
+      )?.description ?? '';
+    const component = entry.arguments[0].description;
+
+    for (const text of [component, option('--category'), option('--reason')]) {
+      expect(text).toContain(REQUIRED);
+      expect(help.stdout).toContain(text);
+    }
+    expect(option('--list-categories')).toContain(
+      'the component and the other gap-report options are ignored',
+    );
+
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-limits-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      const base = {cwd, category: /** @type {const} */ ('docs_gap'), reason: 'x'};
+      /** @type {Array<[string, (value: string) => Promise<unknown>]>} */
+      const limits = [
+        [component, value => gapReport(value, base)],
+        [option('--reason'), value => gapReport('Button', {...base, reason: value})],
+        [
+          option('--additional-context'),
+          value => gapReport('Button', {...base, detail: value}),
+        ],
+      ];
+      for (const [text, call] of limits) {
+        const limit = Number(/up to (\d+) characters/.exec(text)?.[1]);
+        expect(limit, text).toBeGreaterThan(0);
+        await expect(call('x'.repeat(limit))).resolves.toMatchObject({
+          type: 'gap-report.file',
+        });
+        await expect(call('x'.repeat(limit + 1))).rejects.toMatchObject({
+          code: 'ERR_INVALID_ARGUMENT',
+        });
+      }
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+
+  it('enforces the documented requirement', async () => {
+    for (const [component, options] of [
+      [undefined, {category: 'docs_gap', reason: 'x'}],
+      ['Button', {reason: 'x'}],
+      ['Button', {category: 'docs_gap'}],
+    ]) {
+      await expect(gapReport(component, options)).rejects.toMatchObject({
+        code: 'ERR_MISSING_ARGUMENT',
+      });
+    }
+    await expect(
+      gapReport(undefined, {listCategories: true, category: 'not_real', package: 'nope'}),
+    ).resolves.toMatchObject({type: 'gap-report.categories'});
+  });
+});

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

@@ -20,7 +20,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 {hook as hookApi} from '../../../../api/hook/hook.mjs';
-import {findRelatedBlocks} from '../../../../api/template/template.mjs';
 import {doc as hookCommand} from '../hook.doc.mjs';
 import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
 
@@ -169,24 +168,15 @@ export function registerHook(program) {
                   )
                 : formatHookFull(result.data);
 
-          // Show related block templates from relatedComponents
-          const relatedComps = result.data.relatedComponents || [];
-          /** @type {import('../../../../api/template/template.mjs').DiscoveredTemplate[]} */
-          const allBlocks = [];
-          for (const comp of relatedComps) {
-            const blocks = await findRelatedBlocks(comp);
-            for (const b of blocks) {
-              if (!allBlocks.some(existing => existing.dirName === b.dirName)) {
-                allBlocks.push(b);
-              }
-            }
-          }
-
+          // Text projects the envelope only. Block templates are JSON-backed
+          // under `component <name> --blocks`.
+          const related = result.data.relatedComponents ?? [];
           emit(
             code(doc),
-            allBlocks.length > 0 && section('Related block templates'),
-            allBlocks.length > 0 &&
-              records(allBlocks, {fields: ['dirName', 'description']}),
+            related.length > 0 &&
+              text(
+                `Block templates: ${run} component <name> --blocks for ${related.join(', ')}`,
+              ),
           );
           break;
         }

package/clients/cli/commands/hook.text-projection.test.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx hook <name>` text is a projection of `hook.detail`: it shows
+ * nothing the JSON envelope does not carry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
+
+const HOOK = 'useAnnounce';
+
+describe('hook detail text projection', () => {
+  it('prints no block templates that the JSON envelope lacks', async () => {
+    const json = await runCli(['--json', 'hook', HOOK]);
+    expect(json.status).toBe(0);
+    const envelope = JSON.parse(json.stdout);
+    expect(envelope.type).toBe('hook.detail');
+    const related = envelope.data.relatedComponents;
+    expect(related.length).toBeGreaterThan(0);
+
+    const blockNames = [];
+    for (const component of related) {
+      for (const block of await findRelatedBlocks(component)) {
+        blockNames.push(block.dirName);
+      }
+    }
+    expect(blockNames.length).toBeGreaterThan(0);
+
+    const text = await runCli(['hook', HOOK]);
+    expect(text.status).toBe(0);
+    const shownButNotInJson = blockNames.filter(
+      name => text.stdout.includes(name) && !json.stdout.includes(name),
+    );
+    expect(shownButNotInJson).toEqual([]);
+  });
+
+  it('points at the JSON-backed block lookup for each related component', async () => {
+    const text = await runCli(['hook', HOOK]);
+    expect(text.stdout).toMatch(/component <name> --blocks/);
+    expect(text.stdout).toContain('VisuallyHidden');
+    expect(text.stdout).toContain('Toast');
+  });
+});