@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/api/discover/discover.mjs

@@ -3,55 +3,193 @@
 /**
  * @file Programmatic API for the discover command — dispatcher + barrel.
  *
- * `discover()` keeps the exact same signature and response union it always had,
- * so `api/index.mjs` and the CLI consumer are untouched. Its only job now is to
- * discover the external packages (via ./_adapter) and route to the leaf that
- * owns each response shape:
+ * `discover()` browses the integrations a project has and, through discover
+ * sources, the ones it could add. It only reads: the package manager installs.
+ * Its job is to resolve the project and its sources (via ./_adapter) and route
+ * to the leaf that owns each response shape:
  *
- *   discover.list        -> ./list/list.mjs
- *   discover.detail      -> ./detail/detail.mjs
- *   discover.detail.doc  -> ./detail/doc/doc.mjs
- *   discover.search      -> ./search/search.mjs
+ *   discover                         -> ./list/list.mjs        discover.list
+ *   discover <package>[@<version>]   -> ./detail/detail.mjs    discover.detail
+ *   discover <package>/<Component>   -> ./detail/doc/doc.mjs   discover.detail.doc
+ *   discover <package>/<item>        -> ./detail/item/item.mjs discover.item
+ *   discover <words>                 -> ./search/search.mjs    discover.search (always a list)
  *
- * @position api/discover — thin router over ./_adapter + the discover leaves.
+ * Source results are additive: they ride in `meta.available`/`meta.sources`,
+ * in extra fields, or as extra search matches, so every existing field keeps
+ * its meaning.
+ *
+ * @position api/discover — thin router over ./_adapter, ./_catalog-view, and
+ *   the discover leaves.
  */
 
-import {discoverPackages} from './_adapter.mjs';
+import {
+  addCommand,
+  callSources,
+  declaredDependencies,
+  describeInstalled,
+  discoverPackages,
+  findComponent,
+  hasSources,
+} from './_adapter.mjs';
+import {
+  availableEntries,
+  catalogState,
+  searchItems,
+  withLatest,
+} from './_catalog-view.mjs';
 import {list} from './list/list.mjs';
 import {detail} from './detail/detail.mjs';
-import {doc} from './detail/doc/doc.mjs';
+import {doc, docFromResult} from './detail/doc/doc.mjs';
+import {item} from './detail/item/item.mjs';
 import {search} from './search/search.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
+import {DISCOVER_KINDS} from '../../authoring/discover/parse.mjs';
+
+const DEFAULT_LIMIT = 20;
+
+/** @type {import('./_adapter.mjs').CatalogResult} */
+const NO_CATALOG = {sources: [], packages: []};
+
+/**
+ * Split a package-shaped query: `name`, `name@version`, or `name/item`, with an
+ * optional `@scope/` prefix on the name.
+ * @param {string} query
+ * @returns {{scoped: boolean, name: string, version?: string, item?: string}}
+ */
+function splitTarget(query) {
+  const scoped = query.startsWith('@');
+  const firstSlash = query.indexOf('/');
+  let head = query;
+  /** @type {string | undefined} */
+  let rest;
+  const split = scoped
+    ? firstSlash < 0
+      ? -1
+      : query.indexOf('/', firstSlash + 1)
+    : firstSlash;
+  if (split > 0) {
+    head = query.slice(0, split);
+    rest = query.slice(split + 1) || undefined;
+  }
+  const at = head.indexOf('@', 1);
+  return {
+    scoped,
+    name: at > 0 ? head.slice(0, at) : head,
+    ...(at > 0 && head.slice(at + 1) ? {version: head.slice(at + 1)} : {}),
+    ...(rest ? {item: rest} : {}),
+  };
+}
+
+/**
+ * @param {{type?: unknown, installed?: boolean, available?: boolean, limit?: unknown}} options
+ */
+function checkOptions({type, installed, available, limit}) {
+  if (
+    type != null &&
+    !(/** @type {readonly unknown[]} */ (DISCOVER_KINDS).includes(type))
+  ) {
+    throw new AstryxError(
+      `Unknown --type "${String(type)}"`,
+      DISCOVER_KINDS.map(kind => ({name: kind, reason: 'item kind'})),
+      ERROR_CODES.ERR_INVALID_OPTION,
+    );
+  }
+  if (installed && available) {
+    throw new AstryxError(
+      '--installed and --available cannot be used together',
+      undefined,
+      ERROR_CODES.ERR_INVALID_OPTION,
+    );
+  }
+  if (
+    limit != null &&
+    !(typeof limit === 'number' && Number.isInteger(limit) && limit > 0)
+  ) {
+    throw new AstryxError(
+      `--limit must be a positive integer, not "${String(limit)}"`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_OPTION,
+    );
+  }
+}
+
+/**
+ * Items a source lists for a package that look like the one asked for: names
+ * that contain it, else the closest few by spelling.
+ * @param {import('../../authoring/discover/type.js').DiscoverPackage} entry
+ * @param {string} wanted
+ * @returns {Array<{name: string, reason: string}>}
+ */
+function similarItems(entry, wanted) {
+  const lower = wanted.toLowerCase();
+  const names = [...new Set(entry.contributions.map(c => c.name))];
+  const hits = names.filter(name => name.toLowerCase().includes(lower));
+  const picked =
+    hits.length > 0
+      ? hits.slice(0, 5)
+      : names
+          .map(name => ({
+            name,
+            distance: levenshteinDistance(lower, name.toLowerCase()),
+          }))
+          .filter(m => m.distance <= 3)
+          .sort((a, b) => a.distance - b.distance)
+          .slice(0, 5)
+          .map(m => m.name);
+  return picked.map(name => ({
+    name: `${entry.package}/${name}`,
+    reason: 'similar name',
+  }));
+}
 
 /**
  * @param {string} [query]
- * @param {object} [options]
- * @param {boolean} [options.components]
- * @param {string} [options.lang]
- * @param {boolean} [options.zh]
+ * @param {import('./discover.type.mjs').DiscoverOptions} [options]
  * @returns {Promise<
  *   import('./discover.type.mjs').DiscoverListResponse |
  *   import('./discover.type.mjs').DiscoverDetailResponse |
  *   import('./discover.type.mjs').DiscoverDetailDocResponse |
+ *   import('./discover.type.mjs').DiscoverItemResponse |
  *   import('./discover.type.mjs').DiscoverSearchResponse
  * >}
  */
 export async function discover(query, options = {}) {
-  const {lang = null, zh = false} = options;
-  const {packages, configured} = await discoverPackages();
+  const {lang = null, zh = false, type, limit} = options;
+  checkOptions(options);
+  const only = options.installed
+    ? /** @type {const} */ ('installed')
+    : options.available
+      ? /** @type {const} */ ('available')
+      : undefined;
+
+  const {packages: scanned, configured, project} = await discoverPackages();
+  const withSources = hasSources(project);
+  const packages = await describeInstalled(project, scanned);
+  const declared = declaredDependencies(project);
+  const add = addCommand(project);
 
-  // No discoverable packages — either nothing configured, or configured but
-  // empty. The list leaf owns the empty envelope + `configured` flag. This
-  // short-circuits before query parsing, exactly as the flat command did.
-  if (packages.length === 0) return list(packages, {configured});
+  /** @param {{package?: string, version?: string}} [request] */
+  const catalogFor = async request =>
+    withSources ? await callSources(project, request) : NO_CATALOG;
 
-  // No query: the full package list.
-  if (!query) return list(packages, {configured});
+  // No query, or nothing to look through: the list.
+  if (!query || (packages.length === 0 && !withSources)) {
+    if (!withSources) return list(packages, {configured, type, only});
+    const catalog = await catalogFor();
+    return list(withLatest(packages, catalog), {
+      configured,
+      type,
+      only,
+      available: availableEntries(catalog, packages, declared),
+      sources: catalog.sources,
+    });
+  }
 
-  // A non-string (truthy) query would crash `.startsWith`/`.indexOf` below
-  // with a raw TypeError (no ERR_* code → downgrades to ERR_UNKNOWN). The CLI
-  // only ever passes a string, but the public API must fail with a code.
+  // A non-string (truthy) query would crash the parsing below with a raw
+  // TypeError (no ERR_* code → downgrades to ERR_UNKNOWN). The CLI only ever
+  // passes a string, but the public API must fail with a code.
   if (typeof query !== 'string') {
     throw new AstryxError(
       `Invalid query "${String(query)}"`,
@@ -60,17 +198,63 @@ export async function discover(query, options = {}) {
     );
   }
 
-  // Scoped package query: @scope/name or @scope/name/Component
-  if (query.startsWith('@')) {
-    const slashIdx = query.indexOf('/', query.indexOf('/') + 1);
-    if (slashIdx > 0) {
-      const pkgName = query.slice(0, slashIdx);
-      const compName = query.slice(slashIdx + 1);
-      return await doc(packages, pkgName, compName, {lang, zh});
+  const target = splitTarget(query);
+  const installedNames = new Set(packages.map(p => p.name));
+
+  /**
+   * One package, one version, or one item, once `target.name` is known to be
+   * a package the project or a source has.
+   * @param {import('./_adapter.mjs').CatalogResult} catalog
+   */
+  const packageView = async catalog => {
+    const entry = catalog.packages.find(p => p.package === target.name);
+    const installedAs = entry
+      ? catalogState(entry, installedNames, declared).installedAs
+      : undefined;
+    const context = {catalog: entry, version: target.version, add, installedAs};
+    if (!target.item) return detail(packages, target.name, context);
+    const found = item(packages, target.name, target.item, context);
+    if (found) return found;
+    // Only an installed package has docs to fall back to. For one that is
+    // only in a source, the item is what is unknown, not the package.
+    if (entry && !packages.some(p => p.name === target.name)) {
+      throw new AstryxError(
+        `"${target.item}" not found in ${target.name}`,
+        similarItems(entry, target.item),
+        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+      );
     }
-    return detail(packages, query);
+    return await doc(packages, target.name, target.item, {lang, zh});
+  };
+
+  // An installed component keeps resolving to its full doc, before any source
+  // is asked anything.
+  const installedPkg = packages.find(p => p.name === target.name);
+  if (installedPkg && target.item && !target.version) {
+    const resolved = findComponent([installedPkg], target.item);
+    if (resolved) return await docFromResult(resolved, {lang, zh});
+  }
+
+  if (target.scoped) {
+    return await packageView(
+      await catalogFor({package: target.name, version: target.version}),
+    );
+  }
+
+  const listing = await catalogFor();
+  const isPackage =
+    installedPkg != null ||
+    listing.packages.some(p => p.package === target.name);
+  if (isPackage && (target.version || target.item || target.name === query)) {
+    return await packageView(
+      await catalogFor({package: target.name, version: target.version}),
+    );
   }
 
-  // Free-text search across all packages.
-  return await search(packages, query, {lang, zh});
+  return await search(packages, query, {
+    items: searchItems(packages, listing, declared),
+    type,
+    only,
+    limit: limit ?? DEFAULT_LIMIT,
+  });
 }

package/api/discover/discover.test.mjs

@@ -68,10 +68,19 @@ describe('discover() dispatcher routing', () => {
   it('free-text query with multiple matches -> discover.search envelope', async () => {
     // 'a' is a substring of both Alpha and Beta (no exact match), so the search
     // leaf returns the multi-match discover.search envelope. Proves free-text
-    // routing reaches the search leaf and projects its envelope.
+    // routing reaches the search leaf and projects its envelope. Search also
+    // matches package names, so the package itself is listed after them.
     const r = await discover('a');
     expect(r.type).toBe('discover.search');
-    expect(r.data.matches.map(m => m.component).sort()).toEqual(['Alpha', 'Beta']);
+    expect(
+      r.data.matches.filter(m => m.kind === 'component').map(m => m.component),
+    ).toEqual(['Alpha', 'Beta']);
+    expect(r.data.matches).toContainEqual({
+      package: '@acme/widgets',
+      component: '@acme/widgets',
+      kind: 'package',
+      installed: true,
+    });
   });
 
   it('free-text query with no match still routes to the search leaf (coded not-found)', async () => {

package/api/discover/discover.type.d.mts

@@ -2,20 +2,40 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverListResponse = {
     type: "discover.list";
+    /**
+     * The integrations the project loads.
+     */
     data: DiscoverListEntry[];
     /**
-     * Present when the list is empty so
-     * callers can distinguish "no packages configured" from "configured but
-     * nothing discovered".
+     * Present when the list is empty, and
+     * whenever the project has a discover source.
+     */
+    meta?: DiscoverListMeta | undefined;
+};
+export type DiscoverListMeta = {
+    /**
+     * Present when `data` is empty, so callers can
+     * distinguish "no packages configured" from "configured but nothing
+     * discovered".
+     */
+    configured?: boolean | undefined;
+    /**
+     * What the project could add,
+     * one entry per integration, never an alias of a package it has.
      */
-    meta?: {
-        configured: boolean;
-    } | undefined;
+    available?: DiscoverAvailableEntry[] | undefined;
+    /**
+     * What each discover source did.
+     */
+    sources?: DiscoverSourceState[] | undefined;
 };
+/**
+ * An installed integration.
+ */
 export type DiscoverListEntry = {
     name: string;
     category: string;
@@ -23,34 +43,149 @@ export type DiscoverListEntry = {
     version?: string | undefined;
     description?: string | undefined;
     displayName?: string | undefined;
+    /**
+     * Template ids, when it adds any.
+     */
+    templates?: string[] | undefined;
+    /**
+     * Doc topic names, when it adds any.
+     */
+    docs?: string[] | undefined;
+    /**
+     * Theme slugs, when it adds any.
+     */
+    themes?: string[] | undefined;
+    /**
+     * `<version>/<id>`, when it adds any.
+     */
+    codemods?: string[] | undefined;
+    /**
+     * Agent guidance, when a source lists any.
+     */
+    agentDocs?: string[] | undefined;
+    /**
+     * The latest release a discover source knows.
+     */
+    latest?: string | undefined;
+};
+/**
+ * A package the project could add.
+ */
+export type DiscoverAvailableEntry = {
+    name: string;
+    /**
+     * Its latest release.
+     */
+    version?: string | undefined;
+    components: string[];
+    templates?: string[] | undefined;
+    docs?: string[] | undefined;
+    themes?: string[] | undefined;
+    codemods?: string[] | undefined;
+    agentDocs?: string[] | undefined;
+    description?: string | undefined;
+    /**
+     * The integration's other package names.
+     */
+    aliases?: string[] | undefined;
+    /**
+     * The discover source that lists it.
+     */
+    source: string;
+};
+export type DiscoverSourceState = {
+    name: string;
+    /**
+     * `astryx.config`, or the integration that exports it.
+     */
+    from: string;
+    /**
+     * `saved`: the live call
+     * failed and discover used the copy saved at `savedAt`.
+     */
+    status: "fresh" | "saved" | "failed";
+    generatedAt?: string | undefined;
+    complete?: boolean | undefined;
+    savedAt?: string | undefined;
+    error?: string | undefined;
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailResponse = {
     type: "discover.detail";
-    data: DiscoverListEntry;
+    /**
+     * `installed` says whether the project has the package;
+     * `installedVersion` is set when it has another version than the one shown.
+     * `install` is the package-manager command that adds a package the project
+     * does not have; discover prints it and never runs it. `installedAs` names
+     * the package the project has instead, when this one is an alias of it.
+     * `versions` (newest first) comes from a discover source.
+     */
+    data: DiscoverListEntry & {
+        installed: boolean;
+        installedVersion?: string;
+        aliases?: string[];
+        source?: string;
+        installedAs?: string;
+        install?: string;
+        versions?: import("../../authoring/discover/type").DiscoverVersion[];
+    };
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailDocResponse = {
     type: "discover.detail.doc";
     data: import("@astryxdesign/cli/authoring").ComponentDoc;
 };
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover
+ */
+export type DiscoverItemResponse = {
+    type: "discover.item";
+    data: {
+        package: string;
+        version?: string;
+        kind: import("../../authoring/discover/type").DiscoverKind;
+        name: string;
+        title?: string;
+        summary?: string;
+        keywords?: string[];
+        installed: boolean;
+        installedAs?: string;
+        install?: string;
+        source?: string;
+    };
+};
+/**
+ * astryx --json discover <searchterm>
  */
 export type DiscoverSearchResponse = {
     type: "discover.search";
+    /**
+     *   `total` is set when `--limit` cut the list.
+     */
     data: {
         query: string;
         matches: DiscoverSearchEntry[];
+        total?: number;
     };
 };
 export type DiscoverSearchEntry = {
     package: string;
+    /**
+     * The item's name, for every kind; for a package
+     * match, the package name.
+     */
     component: string;
+    kind: import("../../authoring/discover/type").DiscoverKind | "package";
+    /**
+     * Whether the project has the package.
+     */
+    installed: boolean;
+    title?: string | undefined;
+    summary?: string | undefined;
 };
 /**
  * Options for `discover()`.
@@ -59,4 +194,8 @@ export type DiscoverOptions = {
     components?: boolean | undefined;
     lang?: string | undefined;
     zh?: boolean | undefined;
+    type?: import("@astryxdesign/cli/authoring").DiscoverKind | undefined;
+    installed?: boolean | undefined;
+    available?: boolean | undefined;
+    limit?: number | undefined;
 };