@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

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

@@ -277,6 +277,95 @@ describe('component() — integration ownership via config', () => {
     expect(result.data.import).toBe(`${INTEGRATION_NAME}/Toolbar/Search`);
   });
 
+  it('reports every installed candidate for an ambiguous batch selector', async () => {
+    createFixture({extraComponent: 'AppShell'});
+    const result = await component(['MetaAppShell', 'AppShell'], {cwd: tmpDir});
+    expect(result.type).toBe('component.batch');
+    expect(result.data.results[0]).toMatchObject({
+      selector: 'MetaAppShell',
+      status: 'found',
+    });
+    expect(result.data.results[1]).toMatchObject({
+      selector: 'AppShell',
+      status: 'ambiguous',
+      code: 'ERR_UNKNOWN_COMPONENT',
+    });
+    expect(result.data.results[1].candidates).toEqual(
+      expect.arrayContaining([
+        {
+          package: CORE_PACKAGE,
+          component: 'AppShell',
+          kind: 'component',
+          installed: true,
+        },
+        {
+          package: INTEGRATION_NAME,
+          component: 'AppShell',
+          kind: 'component',
+          installed: true,
+        },
+      ]),
+    );
+  });
+
+  it('keeps the single-result envelope for one package-qualified selector', async () => {
+    createFixture();
+    const result = await component('@test/meta@1.2.3/MetaAppShell', {
+      cwd: tmpDir,
+    });
+    expect(result.type).toBe('component.detail');
+    expect(result.data).toMatchObject({
+      name: 'MetaAppShell',
+      package: INTEGRATION_NAME,
+    });
+  });
+
+  it('resolves an exact installed package version and refuses another version', async () => {
+    createFixture();
+    const result = await component(
+      [
+        '@test/meta@1.2.3/MetaAppShell',
+        '@test/meta@9.9.9/MetaAppShell',
+      ],
+      {cwd: tmpDir},
+    );
+    expect(result.type).toBe('component.batch');
+    expect(result.data.results[0]).toMatchObject({
+      selector: '@test/meta@1.2.3/MetaAppShell',
+      status: 'found',
+      result: {type: 'component.detail'},
+    });
+    expect(result.data.results[1]).toMatchObject({
+      selector: '@test/meta@9.9.9/MetaAppShell',
+      status: 'not_found',
+      code: 'ERR_UNKNOWN_PACKAGE',
+      suggestions: [
+        {
+          name: 'astryx discover @test/meta@9.9.9',
+          reason: 'look up this package version',
+        },
+      ],
+    });
+  });
+
+  it('reports a package-qualified selector that conflicts with --package', async () => {
+    createFixture();
+    const result = await component(
+      ['@test/meta/MetaAppShell', 'Button'],
+      {cwd: tmpDir, package: CORE_PACKAGE},
+    );
+    expect(result.type).toBe('component.batch');
+    expect(result.data.results[0]).toMatchObject({
+      selector: '@test/meta/MetaAppShell',
+      status: 'error',
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+    expect(result.data.results[1]).toMatchObject({
+      selector: 'Button',
+      status: 'found',
+    });
+  });
+
   it('JSON list includes integration components as {name, package} objects', async () => {
     createFixture();
     const result = await component(undefined, {cwd: tmpDir, list: true});

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

@@ -16,21 +16,34 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'List components or print component docs',
   description:
-    'Resolves a component by name across core and integration packages and prints ' +
-    'its authored doc, or lists the catalog grouped by category. Boolean flags narrow ' +
-    'a single component to just its props, source, showcase, or example blocks.',
+    'Resolves one or several components by exact selector across core and integration ' +
+    'packages and prints each authored doc, or lists the catalog grouped by category. ' +
+    "Use 'Button', 'widgets/Button', '@acme/widgets/Button', or " +
+    "'@acme/widgets@1.2.3/Button'. A version applies to the package and must match the " +
+    'installed version. Boolean flags narrow every resolved component to just its props, ' +
+    'source, showcase, or example blocks.',
   fn: 'component',
-  args: [{name: 'name', param: 'name', required: false}],
+  args: [
+    {
+      name: 'names',
+      param: 'name',
+      description:
+        'One or more exact selectors. Use Name, package/Name, @scope/package/Name, or @scope/package@version/Name. Two or more return one ordered batch. At most 100 selectors are accepted.',
+      required: false,
+      variadic: true,
+    },
+  ],
   options: [
     {
       flag: '--list',
       param: 'options.list',
-      description: 'List all components grouped by category',
+      description: 'List every component (the same as giving no name)',
     },
     {
       flag: '--category <category>',
       param: 'options.category',
-      description: 'List components in a specific category',
+      description:
+        'List one component group, e.g. --category Layout or --category Avatar (an unknown group lists the valid ones)',
     },
     {
       flag: '--props',
@@ -55,21 +68,26 @@ export const doc = {
     {
       flag: '--package <name>',
       param: 'options.package',
-      description: 'Scope lookup to an external package (e.g. @acme/xds-widgets)',
+      description:
+        'Scope lookup to an external package (e.g. @acme/xds-widgets)',
     },
   ],
   examples: [
     {label: 'Browse the catalog', cli: 'astryx component --list'},
+    {
+      label: 'Look up several components',
+      cli: 'astryx component Button Badge Text',
+    },
     {
       label: 'Props table as JSON',
-      cli: 'astryx component XDSButton --props --json',
+      cli: 'astryx component Button --props --json',
     },
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown component, category, or package, or @astryxdesign/core cannot be resolved',
+      when: 'unknown component, category, or package; more than 100 selectors; any batch row is unresolved; or @astryxdesign/core cannot be resolved',
     },
   ],
   related: ['search', 'hook', 'docs', 'template', 'swizzle'],

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

@@ -14,11 +14,13 @@ export const doc = {
   name: 'discover',
   displayName: 'astryx discover',
   namespace: 'cli/commands',
-  summary: 'Discover external packages and components',
+  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: [
@@ -26,19 +28,61 @@ export const doc = {
       flag: '--components',
       param: 'options.components',
       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.',
+        '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: 'List every component of each package', cli: 'astryx discover --components'},
-    {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 a blank query when packages are discovered',
+      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'],