@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

package/api/discover/_adapter.mjs

@@ -1,81 +1,31 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Shared adapter for the discover leaves: the one place discover reaches
- * the environment.
+ * @file Shared external-package adapter for the discover leaves.
  *
  * Every `discover.*` leaf projects already-resolved data into a typed response;
- * none of them touch the integration system, the filesystem, or a source. This
- * adapter does: it resolves the project's installed integrations and what each
- * one adds, calls every discover source and keeps a saved copy of each answer,
- * locates and loads a component's doc, and names the package manager's add
- * command. Keeping that I/O here (INV21) is what lets `list`, `detail`,
- * `detail/doc`, `detail/item`, and `search` stay pure projections.
+ * none of them touch the integration system or the filesystem directly. This
+ * adapter is the single place that does: it discovers the configured external
+ * packages, locates a component's doc file within them, and loads + validates a
+ * component's docs. Keeping that I/O here (rather than duplicated across leaves)
+ * is what lets `list`, `detail`, `detail/doc`, and `search` stay pure
+ * projections.
  *
- * @position api/discover — orchestration over foundation/config/project,
- *   foundation/integrations, the discovery loaders, and discover sources.
+ * @position api/discover — orchestration over lib/project, lib/package-scanner,
+ *   and lib/component-loader; the discover dispatcher + leaves consume it.
  */
 
-import {createHash} from 'node:crypto';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
 import {Project} from '../../foundation/config/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
 } from './_package-scanner.mjs';
 import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
-import {collectIdentities} from '../../foundation/integrations/contribution-inventory.mjs';
-import {detectPackageManager} from '../../foundation/env/package-manager.mjs';
-import {assertWithin} from '../../foundation/fs/path-safety.mjs';
-import {parseDiscoverCatalog} from '../../authoring/discover/parse.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-const SOURCE_TIMEOUT_MS = 30_000;
-
-const DEPENDENCY_FIELDS = [
-  'dependencies',
-  'devDependencies',
-  'optionalDependencies',
-  'peerDependencies',
-];
-
 /**
  * @typedef {import('./_package-scanner.mjs').ScannedPackage} ScannedPackage
- * @typedef {import('../../authoring/discover/type').DiscoverPackage} DiscoverPackage
- * @typedef {import('../../authoring/discover/type').DiscoverSource} DiscoverSource
- */
-
-/**
- * An installed integration with what it adds, per kind. `components` is the
- * scanned component list the discover leaves have always used.
- * @typedef {ScannedPackage & {
- *   templates?: string[],
- *   docs?: string[],
- *   themes?: string[],
- *   codemods?: string[],
- * }} InstalledPackage
- */
-
-/**
- * What one source did on this run.
- * @typedef {object} SourceState
- * @property {string} name the source's own name, or where it came from when it
- *   gave none
- * @property {string} from `astryx.config`, or the integration that exports it
- * @property {'fresh' | 'saved' | 'failed'} status
- * @property {string} [generatedAt]
- * @property {boolean} [complete]
- * @property {string} [savedAt] when the saved copy in use was written
- * @property {string} [error] why the live call failed
- */
-
-/**
- * Everything every source returned, merged. When two sources list the same
- * package, the earlier source's entry is kept.
- * @typedef {{sources: SourceState[], packages: Array<DiscoverPackage & {source: string}>}} CatalogResult
  */
 
 /**
@@ -118,7 +68,7 @@ function validateDocs(docs) {
  * configured" (`false`) from "configured but nothing discovered" (`true`),
  * which the list leaf surfaces as `meta`.
  *
- * @returns {Promise<{packages: ScannedPackage[], configured: boolean, project: Project}>}
+ * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
  */
 export async function discoverPackages() {
   const project = await Project.load();
@@ -136,323 +86,25 @@ export async function discoverPackages() {
       docsDir: integration.components,
     }));
   if (explicitPackages.length === 0) {
-    return {packages: [], configured: loadedIntegrations.length > 0, project};
+    return {packages: [], configured: loadedIntegrations.length > 0};
   }
 
   const packages = scanAllPackages(
     [],
     /** @type {ScannedPackage[]} */ (/** @type {unknown} */ (explicitPackages)),
   );
-  return {packages, configured: true, project};
-}
-
-/**
- * Every integration the project loads, with what it adds. An integration with
- * no components root is included with `components: []`; one that failed to
- * load is left out (the integration-issues nudge and Doctor report it).
- *
- * @param {Project | undefined} project
- * @param {ScannedPackage[]} scanned the packages {@link discoverPackages} found
- * @returns {Promise<InstalledPackage[]>}
- */
-export async function describeInstalled(project, scanned) {
-  if (project == null) return scanned;
-  const byName = new Map(scanned.map(pkg => [pkg.name, pkg]));
-  /** @type {InstalledPackage[]} */
-  const installed = [];
-  for (const integration of project.loadedIntegrations) {
-    if (integration.__loadError) continue;
-    const base =
-      byName.get(integration.name) ??
-      /** @type {ScannedPackage} */ (
-        /** @type {unknown} */ ({
-          name: integration.name,
-          category: integration.name,
-          version: integration.version,
-          components: [],
-        })
-      );
-    // Components come from the scan above; loading every component doc again
-    // here would only slow the list down.
-    const {identities} = await collectIdentities({
-      ...integration,
-      components: undefined,
-    });
-    installed.push({
-      ...base,
-      templates: identities.templates.map(t => t.id),
-      docs: identities.docs,
-      themes: identities.themes.map(t => t.slug),
-      codemods: identities.codemods.map(c => `${c.version}/${c.id}`),
-    });
-  }
-  return installed;
+  return {packages, configured: true};
 }
 
 /**
- * Whether the project has any discover source: its own `discover` config field,
- * or an integration's `discover` named export (valid or not).
- * @param {Project | undefined} project
- * @returns {boolean}
- */
-export function hasSources(project) {
-  if (project == null) return false;
-  if (typeof project.config?.discover === 'function') return true;
-  return project.loadedIntegrations.some(
-    i => i.__discover != null || i.__discoverError != null,
-  );
-}
-
-/**
- * Package names the project's package.json declares in any dependency field.
- * @param {Project | undefined} project
- * @returns {Set<string>}
- */
-export function declaredDependencies(project) {
-  /** @type {Set<string>} */
-  const names = new Set();
-  if (project == null) return names;
-  try {
-    const pkg = JSON.parse(
-      fs.readFileSync(path.join(project.cwd, 'package.json'), 'utf8'),
-    );
-    for (const field of DEPENDENCY_FIELDS) {
-      for (const name of Object.keys(pkg?.[field] ?? {})) names.add(name);
-    }
-  } catch {
-    // No readable package.json: nothing is declared.
-  }
-  return names;
-}
-
-/**
- * The command that adds a package with the project's package manager. Discover
- * only prints it; it never runs it.
- * @param {Project | undefined} project
- * @returns {(name: string, version?: string) => string}
- */
-export function addCommand(project) {
-  const pm = detectPackageManager(project?.cwd ?? process.cwd());
-  const verb =
-    pm === 'pnpm'
-      ? 'pnpm add'
-      : pm === 'yarn'
-        ? 'yarn add'
-        : pm === 'bun'
-          ? 'bun add'
-          : 'npm install';
-  return (name, version) => `${verb} ${version ? `${name}@${version}` : name}`;
-}
-
-/**
- * The per-user cache directory the saved copies live in, never inside a
- * project. Standard platform locations only.
- * @returns {string}
- */
-export function defaultCacheDir() {
-  const home = os.homedir();
-  if (process.platform === 'win32') {
-    return path.join(
-      process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'),
-      'astryx',
-      'Cache',
-    );
-  }
-  if (process.platform === 'darwin') {
-    return path.join(home, 'Library', 'Caches', 'astryx');
-  }
-  return path.join(
-    process.env.XDG_CACHE_HOME || path.join(home, '.cache'),
-    'astryx',
-  );
-}
-
-/**
- * @param {string} cacheDir
- * @param {string} from
- * @param {{package?: string, version?: string}} request
- */
-function savedCopyPath(cacheDir, from, request) {
-  const key = createHash('sha256')
-    .update(`${from}\n${request.package ?? ''}\n${request.version ?? ''}`)
-    .digest('hex')
-    .slice(0, 32);
-  const dir = path.join(cacheDir, 'discover');
-  return assertWithin(`${key}.json`, dir, {label: 'discover saved copy'});
-}
-
-/**
- * @param {string} file
- * @param {string} label
- */
-function readSavedCopy(file, label) {
-  try {
-    const saved = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return {
-      savedAt: String(saved.savedAt),
-      catalog: parseDiscoverCatalog(saved.catalog, label),
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {string} file
- * @param {import('../../authoring/discover/type').DiscoverCatalog} catalog
- */
-function writeSavedCopy(file, catalog) {
-  try {
-    fs.mkdirSync(path.dirname(file), {recursive: true});
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(
-      tmp,
-      JSON.stringify({savedAt: new Date().toISOString(), catalog}),
-    );
-    fs.renameSync(tmp, file);
-  } catch {
-    // An unwritable cache only costs the offline copy.
-  }
-}
-
-/**
- * @param {DiscoverSource} source
- * @param {{package?: string, version?: string}} request
- * @param {string} label
- * @param {number} timeoutMs
- */
-async function callSource(source, request, label, timeoutMs) {
-  const controller = new AbortController();
-  /** @type {ReturnType<typeof setTimeout> | undefined} */
-  let timer;
-  const timedOut = new Promise((_, reject) => {
-    timer = setTimeout(() => {
-      controller.abort();
-      reject(
-        new Error(`${label} did not answer within ${timeoutMs / 1000} seconds`),
-      );
-    }, timeoutMs);
-  });
-  try {
-    const answer = await Promise.race([
-      Promise.resolve().then(() =>
-        source({signal: controller.signal, ...request}),
-      ),
-      timedOut,
-    ]);
-    return parseDiscoverCatalog(answer, label);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/**
- * Call every discover source — the project's `discover` first, then each
- * integration's in load order — once per distinct function. A source that
- * throws, times out, or returns an invalid catalog falls back to its saved copy;
- * with none, it is reported and adds nothing. The others always count.
- *
- * @param {Project | undefined} project
- * @param {{package?: string, version?: string}} [request] ask for one package,
- *   and optionally one version's contributions
- * @param {{cacheDir?: string, timeoutMs?: number}} [options]
- * @returns {Promise<CatalogResult>}
- */
-export async function callSources(project, request = {}, options = {}) {
-  const {cacheDir = defaultCacheDir(), timeoutMs = SOURCE_TIMEOUT_MS} = options;
-  /** @type {CatalogResult} */
-  const result = {sources: [], packages: []};
-  if (project == null) return result;
-
-  /** @type {Array<{from: string, source?: DiscoverSource, error?: string}>} */
-  const origins = [];
-  if (typeof project.config?.discover === 'function') {
-    origins.push({from: 'astryx.config', source: project.config.discover});
-  }
-  for (const integration of project.loadedIntegrations) {
-    if (integration.__discoverError) {
-      origins.push({from: integration.name, error: integration.__discoverError});
-    } else if (integration.__discover) {
-      origins.push({from: integration.name, source: integration.__discover});
-    }
-  }
-
-  /** @type {Set<unknown>} */
-  const called = new Set();
-  /** @type {Set<string>} */
-  const seen = new Set();
-  const ask = request.package
-    ? {package: request.package, ...(request.version ? {version: request.version} : {})}
-    : {};
-  for (const {from, source, error} of origins) {
-    if (source == null) {
-      result.sources.push({name: from, from, status: 'failed', error});
-      continue;
-    }
-    if (called.has(source)) continue;
-    called.add(source);
-
-    const label = `the discover source from ${from}`;
-    const file = savedCopyPath(cacheDir, from, ask);
-    /** @type {import('../../authoring/discover/type').DiscoverCatalog} */
-    let catalog;
-    try {
-      catalog = await callSource(source, ask, label, timeoutMs);
-      writeSavedCopy(file, catalog);
-      result.sources.push({
-        name: catalog.source.name,
-        from,
-        status: 'fresh',
-        generatedAt: catalog.source.generatedAt,
-        complete: catalog.source.complete,
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const saved = readSavedCopy(file, label);
-      if (saved == null) {
-        result.sources.push({name: from, from, status: 'failed', error: message});
-        continue;
-      }
-      catalog = saved.catalog;
-      result.sources.push({
-        name: catalog.source.name,
-        from,
-        status: 'saved',
-        generatedAt: catalog.source.generatedAt,
-        complete: catalog.source.complete,
-        savedAt: saved.savedAt,
-        error: message,
-      });
-    }
-    for (const pkg of catalog.packages) {
-      if (seen.has(pkg.package)) continue;
-      seen.add(pkg.package);
-      result.packages.push({...pkg, source: catalog.source.name});
-    }
-  }
-  return result;
-}
-
-/** The list and detail entry fields for each item kind, in display order. */
-export const KIND_FIELDS = /** @type {const} */ ([
-  ['component', 'components'],
-  ['template', 'templates'],
-  ['doc', 'docs'],
-  ['theme', 'themes'],
-  ['codemod', 'codemods'],
-  ['agent-doc', 'agentDocs'],
-]);
-
-/**
- * Project a scanned or installed package into the discover list/detail entry
- * shape. Shared by the list and detail leaves so the entry keys (and their
- * order) stay in one place. A kind list appears only when it is not empty.
- * @param {InstalledPackage & {latest?: string}} pkg
+ * Project a scanned package into the discover list/detail entry shape. Shared
+ * by the list and detail leaves so the entry keys (and their order) stay in one
+ * place.
+ * @param {ScannedPackage} pkg
  * @returns {import('./discover.type.mjs').DiscoverListEntry}
  */
 export function toEntry(pkg) {
-  /** @type {Record<string, unknown>} */
-  const entry = {
+  return {
     name: pkg.name,
     category: pkg.category,
     components: pkg.components,
@@ -460,13 +112,6 @@ export function toEntry(pkg) {
     description: pkg.description,
     displayName: pkg.displayName,
   };
-  for (const [, field] of KIND_FIELDS) {
-    if (field === 'components') continue;
-    const values = /** @type {Record<string, unknown>} */ (pkg)[field];
-    if (Array.isArray(values) && values.length > 0) entry[field] = values;
-  }
-  if (pkg.latest) entry.latest = pkg.latest;
-  return /** @type {import('./discover.type.mjs').DiscoverListEntry} */ (entry);
 }
 
 /**

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

@@ -2,24 +2,12 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * 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.
+ * 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.
  *
- * @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]
+ * @param {import('../_package-scanner.mjs').ScannedPackage[]} packages
+ * @param {string} query scoped package name, e.g. `@scope/name`
  * @returns {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;
+export function detail(packages: import("../_package-scanner.mjs").ScannedPackage[], query: string): import("../discover.type.mjs").DiscoverDetailResponse;

package/api/discover/detail/detail.mjs

@@ -1,87 +1,33 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file discover.detail leaf — one package: what it adds, and, when a discover
- * source knows it, every version and the latest one.
+ * @file discover.detail leaf — browse one external package (@scope/name).
  *
- * @position api/discover/detail — pure projection over the packages and catalog
- *   entry resolved by ../_adapter; throws AstryxError (ERR_UNKNOWN_PACKAGE) for
- *   a package neither the project nor any source knows.
+ * @position api/discover/detail — pure projection over the packages resolved by
+ *   ../_adapter; throws AstryxError (ERR_UNKNOWN_PACKAGE) for an unknown scope.
  */
 
 import {toEntry} from '../_adapter.mjs';
-import {catalogEntry, defaultVersion} from '../_catalog-view.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 
 /**
- * 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.
+ * 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.
  *
- * @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]
+ * @param {import('../_package-scanner.mjs').ScannedPackage[]} packages
+ * @param {string} query scoped package name, e.g. `@scope/name`
  * @returns {import('../discover.type.mjs').DiscoverDetailResponse}
  */
-export function detail(packages, name, options = {}) {
-  const {catalog, version, add, installedAs} = options;
-  const pkg = packages.find(p => p.name === name);
-  if (!pkg && !catalog) {
+export function detail(packages, query) {
+  const pkg = packages.find(p => p.name === query);
+  if (!pkg) {
     throw new AstryxError(
-      `Package "${name}" not found`,
+      `Package "${query}" not found`,
       packages.map(p => ({name: p.name, reason: 'available package'})),
       ERROR_CODES.ERR_UNKNOWN_PACKAGE,
     );
   }
-
-  const known = new Set([
-    ...(catalog?.versions.map(v => v.version) ?? []),
-    ...(pkg?.version ? [pkg.version] : []),
-  ]);
-  if (version && !known.has(version)) {
-    const releases = catalog?.versions.filter(v => !v.prerelease) ?? [];
-    throw new AstryxError(
-      `Version "${version}" of ${name} not found`,
-      (releases.length > 0 ? releases.map(v => v.version) : [...known])
-        .slice(0, 5)
-        .map(v => ({name: `${name}@${v}`, reason: 'published version'})),
-      ERROR_CODES.ERR_NOT_FOUND,
-    );
-  }
-
-  const local = pkg != null && (!version || version === pkg.version);
-  /** @type {Record<string, unknown>} */
-  const data = local
-    ? {...toEntry(pkg), installed: true}
-    : {
-        ...catalogEntry(
-          /** @type {NonNullable<typeof catalog>} */ (catalog),
-          version ?? defaultVersion(/** @type {NonNullable<typeof catalog>} */ (catalog)),
-        ),
-        installed: pkg != null,
-        ...(pkg?.version ? {installedVersion: pkg.version} : {}),
-      };
-  if (catalog) {
-    if (catalog.latest) data.latest = catalog.latest;
-    if (catalog.aliases.length > 0) data.aliases = catalog.aliases;
-    data.source = catalog.source;
-  }
-  if (!pkg) {
-    if (installedAs) data.installedAs = installedAs;
-    else if (add) data.install = add(name, version);
-  }
-  if (catalog) data.versions = catalog.versions;
-  return {
-    type: 'discover.detail',
-    data: /** @type {import('../discover.type.mjs').DiscoverDetailResponse['data']} */ (
-      data
-    ),
-  };
+  return {type: 'discover.detail', data: toEntry(pkg)};
 }

package/api/discover/detail/detail.test.mjs

@@ -36,7 +36,6 @@ describe('discover.detail leaf', () => {
       category: '@acme/widgets',
       components: ['Alpha', 'Beta'],
       version: '1.2.3',
-      installed: true,
     });
   });
 
@@ -56,87 +55,3 @@ describe('discover.detail leaf', () => {
     ]);
   });
 });
-
-describe('discover.detail leaf with a discover source', () => {
-  /** @type {any} */
-  const catalog = {
-    package: '@acme/charts',
-    integration: 'acme-charts',
-    aliases: ['@acme/charts-legacy'],
-    latest: '2.0.0',
-    source: 'Acme',
-    versions: [
-      {version: '2.1.0-beta.1', publishedAt: '2026-09-30T00:00:00.000Z', prerelease: true, status: 'ok'},
-      {version: '2.0.0', publishedAt: '2026-09-20T00:00:00.000Z', prerelease: false, status: 'ok'},
-      {version: '1.0.0', publishedAt: null, prerelease: false, status: 'manifest_load_error'},
-    ],
-    contributions: [
-      {kind: 'component', name: 'Chart'},
-      {kind: 'template', name: 'pages/Report'},
-    ],
-  };
-  /** @param {string} name @param {string} [version] */
-  const add = (name, version) => `pnpm add ${version ? `${name}@${version}` : name}`;
-
-  it('describes a package the project does not have, with the command that adds it', () => {
-    expect(detail(PACKAGES, '@acme/charts', {catalog, add}).data).toEqual({
-      name: '@acme/charts',
-      category: '@acme/charts',
-      components: ['Chart'],
-      version: '2.0.0',
-      templates: ['pages/Report'],
-      installed: false,
-      latest: '2.0.0',
-      aliases: ['@acme/charts-legacy'],
-      source: 'Acme',
-      install: 'pnpm add @acme/charts',
-      versions: catalog.versions,
-    });
-  });
-
-  it('describes any version, prereleases included', () => {
-    const {data} = detail(PACKAGES, '@acme/charts', {catalog, add, version: '2.1.0-beta.1'});
-    expect(data.version).toBe('2.1.0-beta.1');
-    expect(data.install).toBe('pnpm add @acme/charts@2.1.0-beta.1');
-  });
-
-  it('refuses a version that was never published, and suggests releases', () => {
-    let err;
-    try {
-      detail(PACKAGES, '@acme/charts', {catalog, add, version: '3.0.0'});
-    } catch (e) {
-      err = e;
-    }
-    expect(err).toBeInstanceOf(AstryxError);
-    expect(err.code).toBe('ERR_NOT_FOUND');
-    expect(err.suggestions.map(s => s.name)).toEqual([
-      '@acme/charts@2.0.0',
-      '@acme/charts@1.0.0',
-    ]);
-  });
-
-  it('names the package the project has instead of offering an alias', () => {
-    const {data} = detail(PACKAGES, '@acme/charts', {
-      catalog,
-      add,
-      installedAs: '@acme/charts-legacy',
-    });
-    expect(data.installedAs).toBe('@acme/charts-legacy');
-    expect(data).not.toHaveProperty('install');
-  });
-
-  it("keeps describing the installed copy from the project, with the source's versions", () => {
-    const {data} = detail(PACKAGES, '@acme/widgets', {
-      catalog: {...catalog, package: '@acme/widgets', latest: '1.3.0'},
-      add,
-    });
-    expect(data).toMatchObject({
-      name: '@acme/widgets',
-      components: ['Alpha', 'Beta'],
-      version: '1.2.3',
-      installed: true,
-      latest: '1.3.0',
-    });
-    expect(data).not.toHaveProperty('install');
-  });
-});