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

package/api/discover/_adapter.test.mjs

@@ -0,0 +1,215 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for how the discover adapter calls discover sources: order,
+ * failure isolation, timeouts, and the saved copy. Sources are plain functions
+ * on a stand-in project, and the saved copies go to a temp directory.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {callSources} from './_adapter.mjs';
+
+/**
+ * @param {string} name
+ * @param {object[]} packages
+ */
+function catalog(name, packages) {
+  return {
+    schemaVersion: 1,
+    source: {name, generatedAt: '2026-09-30T00:00:00.000Z', complete: true},
+    packages,
+  };
+}
+
+/**
+ * @param {string} name
+ * @param {object} [extra]
+ */
+function pkg(name, extra = {}) {
+  return {
+    package: name,
+    integration: name,
+    aliases: [],
+    latest: '1.0.0',
+    versions: [
+      {version: '1.0.0', publishedAt: null, prerelease: false, status: 'ok'},
+    ],
+    contributions: [],
+    ...extra,
+  };
+}
+
+/**
+ * @param {{config?: object, integrations?: object[]}} parts
+ * @returns {any}
+ */
+function project({config = {}, integrations = []}) {
+  return {config, loadedIntegrations: integrations, cwd: '/virtual/project'};
+}
+
+let cacheDir;
+
+beforeEach(() => {
+  cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discover-cache-'));
+});
+
+afterEach(() => {
+  fs.rmSync(cacheDir, {recursive: true, force: true});
+});
+
+describe('callSources', () => {
+  it('asks the project source first, then each integration in load order, once per function', async () => {
+    /** @type {string[]} */
+    const calls = [];
+    const shared = vi.fn(async () => {
+      calls.push('shared');
+      return catalog('Shared', [pkg('@a/one')]);
+    });
+    const own = vi.fn(async () => {
+      calls.push('own');
+      return catalog('Own', [pkg('@a/one', {latest: '9.9.9'}), pkg('@a/two')]);
+    });
+
+    const result = await callSources(
+      project({
+        config: {discover: own},
+        integrations: [
+          {name: '@x/first', __discover: shared},
+          {name: '@x/second', __discover: shared},
+        ],
+      }),
+      {},
+      {cacheDir},
+    );
+
+    expect(calls).toEqual(['own', 'shared']);
+    expect(result.sources.map(s => [s.name, s.from, s.status])).toEqual([
+      ['Own', 'astryx.config', 'fresh'],
+      ['Shared', '@x/first', 'fresh'],
+    ]);
+    expect(result.packages.map(p => [p.package, p.latest, p.source])).toEqual([
+      ['@a/one', '9.9.9', 'Own'],
+      ['@a/two', '1.0.0', 'Own'],
+    ]);
+  });
+
+  it('passes the package and version it wants, with an abort signal', async () => {
+    const source = vi.fn(async () => catalog('S', []));
+
+    await callSources(
+      project({integrations: [{name: '@x/src', __discover: source}]}),
+      {package: '@a/one', version: '1.0.0'},
+      {cacheDir},
+    );
+
+    expect(source).toHaveBeenCalledWith({
+      signal: expect.any(globalThis.AbortSignal),
+      package: '@a/one',
+      version: '1.0.0',
+    });
+  });
+
+  it('keeps every other source when one throws, returns bad data, or is not a function', async () => {
+    const result = await callSources(
+      project({
+        integrations: [
+          {
+            name: '@x/throws',
+            __discover: async () => {
+              throw new Error('offline');
+            },
+          },
+          {name: '@x/bad', __discover: async () => ({schemaVersion: 2})},
+          {
+            name: '@x/broken',
+            __discoverError: 'named export "discover" must be a function',
+          },
+          {
+            name: '@x/good',
+            __discover: async () => catalog('Good', [pkg('@a/one')]),
+          },
+        ],
+      }),
+      {},
+      {cacheDir},
+    );
+
+    expect(result.sources.map(s => [s.from, s.status])).toEqual([
+      ['@x/throws', 'failed'],
+      ['@x/bad', 'failed'],
+      ['@x/broken', 'failed'],
+      ['@x/good', 'fresh'],
+    ]);
+    expect(result.sources[0].error).toContain('offline');
+    expect(result.sources[1].error).toContain('schemaVersion 2');
+    expect(result.sources[2].error).toContain('must be a function');
+    expect(result.packages.map(p => p.package)).toEqual(['@a/one']);
+  });
+
+  it('gives up on a source after the timeout and aborts its signal', async () => {
+    /** @type {AbortSignal | undefined} */
+    let seen;
+    const slow = ({signal}) => {
+      seen = signal;
+      return new Promise(() => {});
+    };
+
+    const result = await callSources(
+      project({integrations: [{name: '@x/slow', __discover: slow}]}),
+      {},
+      {cacheDir, timeoutMs: 20},
+    );
+
+    expect(result.sources[0]).toMatchObject({
+      status: 'failed',
+      error: expect.stringContaining('did not answer'),
+    });
+    expect(seen?.aborted).toBe(true);
+  });
+
+  it('uses the copy saved for the same request when a source fails, and says when it was saved', async () => {
+    let online = true;
+    const source = async () => {
+      if (!online) throw new Error('offline');
+      return catalog('S', [pkg('@a/one')]);
+    };
+    const p = project({integrations: [{name: '@x/src', __discover: source}]});
+
+    await callSources(p, {}, {cacheDir});
+    online = false;
+    const offline = await callSources(p, {}, {cacheDir});
+
+    expect(offline.sources[0]).toMatchObject({
+      name: 'S',
+      status: 'saved',
+      error: 'offline',
+      savedAt: expect.any(String),
+    });
+    expect(offline.packages.map(x => x.package)).toEqual(['@a/one']);
+
+    const otherRequest = await callSources(p, {package: '@a/one'}, {cacheDir});
+    expect(otherRequest.sources[0].status).toBe('failed');
+  });
+
+  it('keeps the saved copy in the cache directory, not in the project', async () => {
+    await callSources(
+      project({
+        integrations: [
+          {name: '@x/src', __discover: async () => catalog('S', [])},
+        ],
+      }),
+      {},
+      {cacheDir},
+    );
+
+    expect(fs.readdirSync(path.join(cacheDir, 'discover'))).toHaveLength(1);
+    expect(fs.existsSync('/virtual/project')).toBe(false);
+  });
+
+  it('returns nothing when there is no project', async () => {
+    expect(await callSources(undefined)).toEqual({sources: [], packages: []});
+  });
+});

package/api/discover/_catalog-view.d.mts

@@ -0,0 +1,115 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {import('./_adapter.mjs').InstalledPackage} InstalledPackage
+ * @typedef {import('./_adapter.mjs').CatalogResult} CatalogResult
+ * @typedef {CatalogResult['packages'][number]} CatalogPackage
+ * @typedef {import('../../authoring/discover/type').DiscoverKind} DiscoverKind
+ */
+/**
+ * An item search looks through. `kind: 'package'` is a package itself.
+ * @typedef {object} SearchItem
+ * @property {string} package
+ * @property {DiscoverKind | 'package'} kind
+ * @property {string} name
+ * @property {boolean} installed
+ * @property {string} [title]
+ * @property {string} [summary]
+ * @property {string[]} [keywords]
+ * @property {string} [description]
+ */
+/**
+ * Group a version's contributions into the entry fields, one list per kind.
+ * `components` is always present, like on an installed entry.
+ * @param {CatalogPackage['contributions']} contributions
+ * @returns {Record<string, string[]>}
+ */
+export function kindLists(contributions: CatalogPackage["contributions"]): Record<string, string[]>;
+/**
+ * Whether an entry adds at least one item of `kind`.
+ * @param {Record<string, unknown>} entry
+ * @param {DiscoverKind} kind
+ * @returns {boolean}
+ */
+export function hasKind(entry: Record<string, unknown>, kind: DiscoverKind): boolean;
+/**
+ * Where a catalog package stands against the project.
+ * @param {CatalogPackage} pkg
+ * @param {Set<string>} installedNames
+ * @param {Set<string>} declared
+ * @returns {{state: 'installed' | 'declared' | 'alias' | 'available', installedAs?: string}}
+ */
+export function catalogState(pkg: CatalogPackage, installedNames: Set<string>, declared: Set<string>): {
+    state: "installed" | "declared" | "alias" | "available";
+    installedAs?: string;
+};
+/**
+ * The version a catalog package shows by default.
+ * @param {CatalogPackage} pkg
+ * @returns {string | undefined}
+ */
+export function defaultVersion(pkg: CatalogPackage): string | undefined;
+/**
+ * Project a catalog package into the entry shape installed packages use.
+ * @param {CatalogPackage} pkg
+ * @param {string | undefined} version
+ */
+export function catalogEntry(pkg: CatalogPackage, version: string | undefined): {
+    description?: string | undefined;
+    version?: string | undefined;
+    name: string;
+    category: string;
+    components: string[];
+};
+/**
+ * What the project could add: every catalog package it does not have, once per
+ * integration (the first name a source lists), never an alias of one it has.
+ * @param {CatalogResult} catalog
+ * @param {InstalledPackage[]} installed
+ * @param {Set<string>} declared
+ */
+export function availableEntries(catalog: CatalogResult, installed: InstalledPackage[], declared: Set<string>): {
+    source: string;
+    aliases?: string[] | undefined;
+    description?: string | undefined;
+    version?: string | undefined;
+    name: string;
+    components: string[];
+}[];
+/**
+ * Installed packages with the latest release a source knows for each.
+ * @param {InstalledPackage[]} installed
+ * @param {CatalogResult} catalog
+ * @returns {Array<InstalledPackage & {latest?: string}>}
+ */
+export function withLatest(installed: InstalledPackage[], catalog: CatalogResult): Array<InstalledPackage & {
+    latest?: string;
+}>;
+/**
+ * Everything search looks through besides installed components (which the
+ * search leaf keeps resolving the way it always has): installed packages and
+ * their other items, and every package the project could add with its items.
+ * @param {InstalledPackage[]} installed
+ * @param {CatalogResult} catalog
+ * @param {Set<string>} declared
+ * @returns {SearchItem[]}
+ */
+export function searchItems(installed: InstalledPackage[], catalog: CatalogResult, declared: Set<string>): SearchItem[];
+export type InstalledPackage = import("./_adapter.mjs").InstalledPackage;
+export type CatalogResult = import("./_adapter.mjs").CatalogResult;
+export type CatalogPackage = CatalogResult["packages"][number];
+export type DiscoverKind = import("../../authoring/discover/type").DiscoverKind;
+/**
+ * An item search looks through. `kind: 'package'` is a package itself.
+ */
+export type SearchItem = {
+    package: string;
+    kind: DiscoverKind | "package";
+    name: string;
+    installed: boolean;
+    title?: string | undefined;
+    summary?: string | undefined;
+    keywords?: string[] | undefined;
+    description?: string | undefined;
+};

package/api/discover/_catalog-view.mjs

@@ -0,0 +1,203 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Pure views over discover sources' catalogs: which catalog packages the
+ * project already has, what it could add, and the items search looks through.
+ * No I/O; the adapter supplies every input.
+ *
+ * @position api/discover — shared by the list, detail, item, and search leaves.
+ */
+
+import {KIND_FIELDS} from './_adapter.mjs';
+
+/**
+ * @typedef {import('./_adapter.mjs').InstalledPackage} InstalledPackage
+ * @typedef {import('./_adapter.mjs').CatalogResult} CatalogResult
+ * @typedef {CatalogResult['packages'][number]} CatalogPackage
+ * @typedef {import('../../authoring/discover/type').DiscoverKind} DiscoverKind
+ */
+
+/**
+ * An item search looks through. `kind: 'package'` is a package itself.
+ * @typedef {object} SearchItem
+ * @property {string} package
+ * @property {DiscoverKind | 'package'} kind
+ * @property {string} name
+ * @property {boolean} installed
+ * @property {string} [title]
+ * @property {string} [summary]
+ * @property {string[]} [keywords]
+ * @property {string} [description]
+ */
+
+/**
+ * Group a version's contributions into the entry fields, one list per kind.
+ * `components` is always present, like on an installed entry.
+ * @param {CatalogPackage['contributions']} contributions
+ * @returns {Record<string, string[]>}
+ */
+export function kindLists(contributions) {
+  /** @type {Record<string, string[]>} */
+  const lists = {components: []};
+  for (const [kind, field] of KIND_FIELDS) {
+    const names = contributions.filter(c => c.kind === kind).map(c => c.name);
+    if (names.length > 0 || field === 'components') lists[field] = names;
+  }
+  return lists;
+}
+
+/**
+ * Whether an entry adds at least one item of `kind`.
+ * @param {Record<string, unknown>} entry
+ * @param {DiscoverKind} kind
+ * @returns {boolean}
+ */
+export function hasKind(entry, kind) {
+  const field = KIND_FIELDS.find(([k]) => k === kind)?.[1];
+  const values = field == null ? undefined : entry[field];
+  return Array.isArray(values) && values.length > 0;
+}
+
+/**
+ * Where a catalog package stands against the project.
+ * @param {CatalogPackage} pkg
+ * @param {Set<string>} installedNames
+ * @param {Set<string>} declared
+ * @returns {{state: 'installed' | 'declared' | 'alias' | 'available', installedAs?: string}}
+ */
+export function catalogState(pkg, installedNames, declared) {
+  if (installedNames.has(pkg.package)) return {state: 'installed'};
+  if (declared.has(pkg.package)) return {state: 'declared'};
+  const installedAs = pkg.aliases.find(
+    name => installedNames.has(name) || declared.has(name),
+  );
+  if (installedAs != null) return {state: 'alias', installedAs};
+  return {state: 'available'};
+}
+
+/**
+ * The version a catalog package shows by default.
+ * @param {CatalogPackage} pkg
+ * @returns {string | undefined}
+ */
+export function defaultVersion(pkg) {
+  return pkg.latest ?? pkg.versions[0]?.version;
+}
+
+/**
+ * Project a catalog package into the entry shape installed packages use.
+ * @param {CatalogPackage} pkg
+ * @param {string | undefined} version
+ */
+export function catalogEntry(pkg, version) {
+  const {components, ...others} = kindLists(pkg.contributions);
+  return {
+    name: pkg.package,
+    category: pkg.package,
+    components,
+    ...(version ? {version} : {}),
+    ...(pkg.description ? {description: pkg.description} : {}),
+    ...others,
+  };
+}
+
+/**
+ * What the project could add: every catalog package it does not have, once per
+ * integration (the first name a source lists), never an alias of one it has.
+ * @param {CatalogResult} catalog
+ * @param {InstalledPackage[]} installed
+ * @param {Set<string>} declared
+ */
+export function availableEntries(catalog, installed, declared) {
+  const installedNames = new Set(installed.map(p => p.name));
+  /** @type {Set<string>} */
+  const integrations = new Set();
+  const entries = [];
+  for (const pkg of catalog.packages) {
+    if (catalogState(pkg, installedNames, declared).state !== 'available')
+      continue;
+    if (integrations.has(pkg.integration)) continue;
+    integrations.add(pkg.integration);
+    const version = defaultVersion(pkg);
+    const {category: _category, ...entry} = catalogEntry(pkg, version);
+    entries.push({
+      ...entry,
+      ...(pkg.aliases.length > 0 ? {aliases: pkg.aliases} : {}),
+      source: pkg.source,
+    });
+  }
+  return entries;
+}
+
+/**
+ * Installed packages with the latest release a source knows for each.
+ * @param {InstalledPackage[]} installed
+ * @param {CatalogResult} catalog
+ * @returns {Array<InstalledPackage & {latest?: string}>}
+ */
+export function withLatest(installed, catalog) {
+  const byName = new Map(catalog.packages.map(p => [p.package, p]));
+  return installed.map(pkg => {
+    const latest = byName.get(pkg.name)?.latest;
+    return latest ? {...pkg, latest} : pkg;
+  });
+}
+
+/**
+ * Everything search looks through besides installed components (which the
+ * search leaf keeps resolving the way it always has): installed packages and
+ * their other items, and every package the project could add with its items.
+ * @param {InstalledPackage[]} installed
+ * @param {CatalogResult} catalog
+ * @param {Set<string>} declared
+ * @returns {SearchItem[]}
+ */
+export function searchItems(installed, catalog, declared) {
+  /** @type {SearchItem[]} */
+  const items = [];
+  for (const pkg of installed) {
+    items.push({
+      package: pkg.name,
+      kind: 'package',
+      name: pkg.name,
+      installed: true,
+      ...(pkg.description ? {description: pkg.description} : {}),
+    });
+    for (const [kind, field] of KIND_FIELDS) {
+      if (kind === 'component') continue;
+      const names = /** @type {Record<string, unknown>} */ (pkg)[field];
+      if (!Array.isArray(names)) continue;
+      for (const name of names) {
+        items.push({package: pkg.name, kind, name, installed: true});
+      }
+    }
+  }
+  const installedNames = new Set(installed.map(p => p.name));
+  /** @type {Set<string>} */
+  const integrations = new Set();
+  for (const pkg of catalog.packages) {
+    if (catalogState(pkg, installedNames, declared).state !== 'available')
+      continue;
+    if (integrations.has(pkg.integration)) continue;
+    integrations.add(pkg.integration);
+    items.push({
+      package: pkg.package,
+      kind: 'package',
+      name: pkg.package,
+      installed: false,
+      ...(pkg.description ? {description: pkg.description} : {}),
+    });
+    for (const c of pkg.contributions) {
+      items.push({
+        package: pkg.package,
+        kind: c.kind,
+        name: c.name,
+        installed: false,
+        ...(c.title ? {title: c.title} : {}),
+        ...(c.summary ? {summary: c.summary} : {}),
+        ...(c.keywords ? {keywords: c.keywords} : {}),
+      });
+    }
+  }
+  return items;
+}

package/api/discover/_catalog-view.test.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the pure views over discover sources' catalogs.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  availableEntries,
+  catalogState,
+  kindLists,
+  searchItems,
+  withLatest,
+} from './_catalog-view.mjs';
+
+/**
+ * @param {string} name
+ * @param {string} integration
+ * @param {object} [extra]
+ * @returns {any}
+ */
+function entry(name, integration, extra = {}) {
+  return {
+    package: name,
+    integration,
+    aliases: [],
+    latest: '1.0.0',
+    versions: [],
+    contributions: [{kind: 'component', name: 'A'}],
+    source: 'S',
+    ...extra,
+  };
+}
+
+const CATALOG = {
+  sources: [],
+  packages: [
+    entry('@acme/ui', 'acme-ui', {aliases: ['@acme/ui-classic']}),
+    entry('@acme/ui-classic', 'acme-ui', {aliases: ['@acme/ui']}),
+    entry('@acme/charts', 'charts', {
+      latest: '2.0.0',
+      contributions: [{kind: 'theme', name: 'ocean'}],
+    }),
+  ],
+};
+
+/** @param {string} name @returns {any} */
+const installed = name => ({name, category: name, components: []});
+
+describe('availableEntries', () => {
+  it('offers each integration once, under the first name a source lists', () => {
+    expect(
+      availableEntries(CATALOG, [], new Set()).map(e => [e.name, e.aliases]),
+    ).toEqual([
+      ['@acme/ui', ['@acme/ui-classic']],
+      ['@acme/charts', undefined],
+    ]);
+  });
+
+  it('never offers an integration the project has under another name', () => {
+    expect(
+      availableEntries(CATALOG, [installed('@acme/ui-classic')], new Set()).map(
+        e => e.name,
+      ),
+    ).toEqual(['@acme/charts']);
+  });
+
+  it('does not offer a package the project declares, even when it did not load', () => {
+    expect(
+      availableEntries(CATALOG, [], new Set(['@acme/charts'])).map(e => e.name),
+    ).toEqual(['@acme/ui']);
+  });
+
+  it('describes an entry the way an installed one is described', () => {
+    expect(availableEntries(CATALOG, [], new Set())[1]).toEqual({
+      name: '@acme/charts',
+      components: [],
+      version: '2.0.0',
+      themes: ['ocean'],
+      source: 'S',
+    });
+  });
+});
+
+describe('catalogState', () => {
+  it('names the package the project has instead', () => {
+    expect(
+      catalogState(CATALOG.packages[0], new Set(['@acme/ui-classic']), new Set()),
+    ).toEqual({state: 'alias', installedAs: '@acme/ui-classic'});
+  });
+});
+
+describe('withLatest', () => {
+  it('adds the latest release a source knows to an installed package', () => {
+    expect(withLatest([installed('@acme/charts')], CATALOG)[0]).toMatchObject({
+      latest: '2.0.0',
+    });
+  });
+});
+
+describe('kindLists', () => {
+  it('groups items by kind, always with components', () => {
+    expect(
+      kindLists([
+        {kind: 'theme', name: 'ocean'},
+        {kind: 'component', name: 'A'},
+      ]),
+    ).toEqual({components: ['A'], themes: ['ocean']});
+  });
+});
+
+describe('searchItems', () => {
+  it('covers installed packages and their other items, then what could be added', () => {
+    const items = searchItems(
+      [{...installed('@acme/widgets'), templates: ['pages/Home']}],
+      CATALOG,
+      new Set(),
+    );
+    expect(items.map(i => [i.package, i.kind, i.name, i.installed])).toEqual([
+      ['@acme/widgets', 'package', '@acme/widgets', true],
+      ['@acme/widgets', 'template', 'pages/Home', true],
+      ['@acme/ui', 'package', '@acme/ui', false],
+      ['@acme/ui', 'component', 'A', false],
+      ['@acme/charts', 'package', '@acme/charts', false],
+      ['@acme/charts', 'theme', 'ocean', false],
+    ]);
+  });
+});

package/api/discover/detail/detail.d.mts

@@ -2,12 +2,24 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Build the discover.detail response for a scoped package name. Throws
- * AstryxError (ERR_UNKNOWN_PACKAGE) — with the available packages as
- * suggestions — when no package matches.
+ * Build the discover.detail response for one package. The project's installed
+ * copy describes itself; any other version is described by its source. For a
+ * package the project does not have, `install` is the package-manager command
+ * that adds it — printed, never run.
  *
- * @param {import('../_package-scanner.mjs').ScannedPackage[]} packages
- * @param {string} query scoped package name, e.g. `@scope/name`
+ * @param {import('../_adapter.mjs').InstalledPackage[]} packages
+ * @param {string} name package name, e.g. `@scope/name`
+ * @param {{
+ *   catalog?: import('../_catalog-view.mjs').CatalogPackage,
+ *   version?: string,
+ *   add?: (name: string, version?: string) => string,
+ *   installedAs?: string,
+ * }} [options]
  * @returns {import('../discover.type.mjs').DiscoverDetailResponse}
  */
-export function detail(packages: import("../_package-scanner.mjs").ScannedPackage[], query: string): import("../discover.type.mjs").DiscoverDetailResponse;
+export function detail(packages: import("../_adapter.mjs").InstalledPackage[], name: string, options?: {
+    catalog?: import("../_catalog-view.mjs").CatalogPackage;
+    version?: string;
+    add?: (name: string, version?: string) => string;
+    installedAs?: string;
+}): import("../discover.type.mjs").DiscoverDetailResponse;