@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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 () => {
@@ -87,6 +88,53 @@ 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.'}, props: []};\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\n',
+    );
+  });
+});
+
 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.
@@ -101,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.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

@@ -13,30 +13,76 @@ export const doc = {
   type: 'command',
   name: 'discover',
   displayName: 'astryx discover',
-  namespace: 'cli',
-  summary: 'Discover external packages and components',
+  namespace: 'cli/commands',
+  summary:
+    'Browse and search integrations: the ones you have and the ones you could add',
   description:
-    'Explores components contributed by configured external packages and integrations. ' +
-    'With no query it lists those packages; an @scope/name query browses one package; ' +
-    'an @scope/name/Component path or a free-text term resolves to a component doc.',
+    'Lists the integrations this project loads and, when it has a discover source, the ones it could add, with what each one adds. ' +
+    'A package query shows one package: what it adds, every version a source knows, and the command that adds it. ' +
+    "An @scope/name/Component path prints an installed component's doc; any other item path shows that item. " +
+    'Anything else, even an exact component name, searches every item and package and lists the matches. Discover only reads: your package manager installs, updates, and removes packages.',
   fn: 'discover',
   args: [{name: 'query', param: 'query', required: false}],
   options: [
     {
       flag: '--components',
       param: 'options.components',
-      description: 'List components only',
+      description:
+        'In the package list, print every component, and every other item, 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.',
+    },
+    {
+      flag: '--type <kind>',
+      param: 'options.type',
+      description:
+        'Only one kind: component, template, doc, theme, codemod, or agent-doc. In the list, only packages that add it; in a search, only items of that kind.',
+    },
+    {
+      flag: '--installed',
+      param: 'options.installed',
+      description:
+        'Only what this project has. Cannot be set with --available.',
+    },
+    {
+      flag: '--available',
+      param: 'options.available',
+      description:
+        'Only what this project could add. Cannot be set with --installed.',
+    },
+    {
+      flag: '--limit <n>',
+      param: 'options.limit',
+      description:
+        'Max number of search results, a positive integer (default 20).',
     },
   ],
   examples: [
-    {label: 'List packages', cli: 'astryx discover --json'},
-    {label: 'Browse a package', cli: 'astryx discover @acme/ui'},
+    {
+      label: 'List what you have and what you could add',
+      cli: 'astryx discover',
+    },
+    {
+      label: 'List every component of each package',
+      cli: 'astryx discover --components',
+    },
+    {
+      label: 'Only packages that add themes',
+      cli: 'astryx discover --type theme',
+    },
+    {
+      label: 'Browse a package and its versions',
+      cli: 'astryx discover @acme/ui',
+    },
+    {label: 'See one version', cli: 'astryx discover @acme/ui@2.1.0'},
+    {
+      label: 'Search templates you could add',
+      cli: 'astryx discover dashboard --type template --available',
+    },
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown package or component, a malformed doc, or an empty free-text query',
+      when: 'unknown package, version, component, or item; a malformed doc; an invalid --type or --limit; --installed with --available; or a blank query when packages are discovered',
     },
   ],
   related: ['component', 'search', 'template'],