@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/component/component.type.mjs

@@ -18,9 +18,6 @@
  * astryx --json component --category Form         -> component.list (filtered)
  * astryx --json component --list --detail compact -> component.list (data.detail='compact')
  * astryx --json component --list --detail full    -> component.list (data.detail='full')
- * component([])                                  -> component.batch (data.count=0)
- * component(['Button'])                          -> component.batch (data.count=1)
- * astryx --json component Button Badge            -> component.batch
  * astryx --json component Button                  -> component.detail
  * astryx --json component Button --props          -> component.detail.props
  * astryx --json component Button --source         -> component.detail.source
@@ -52,47 +49,6 @@
  * )} ComponentListData
  */
 
-/**
- * `component(string[])` always returns this type, including empty and one-item
- * arrays. The CLI returns it for two or more positional selectors.
- * @typedef {import('../../foundation/response/batch.type.mjs').BatchResponse<
- *   'component.batch',
- *   ComponentSingleResponse,
- *   ComponentBatchCandidate
- * >} ComponentBatchResponse
- */
-
-/**
- * One installed component that makes an unqualified selector ambiguous.
- * Keys match a component row in `discover.search` so a caller does not learn a
- * second candidate shape.
- * @typedef {object} ComponentBatchCandidate
- * @property {string} package
- * @property {string} component
- * @property {'component'} kind
- * @property {true} installed
- */
-
-/**
- * The response a successful single selector would have returned.
- * @typedef {(
- *   | ComponentDetailResponse
- *   | ComponentDetailPropsResponse
- *   | ComponentDetailSourceResponse
- *   | ComponentDetailShowcaseResponse
- *   | ComponentDetailBlocksResponse
- * )} ComponentSingleResponse
- */
-
-/**
- * One row per requested selector, in argument order. Duplicate selectors keep
- * duplicate rows.
- * @typedef {import('../../foundation/response/batch.type.mjs').BatchRow<
- *   ComponentSingleResponse,
- *   ComponentBatchCandidate
- * >} ComponentBatchResult
- */
-
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can

package/api/discover/_adapter.d.mts

@@ -12,78 +12,20 @@
  * 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 function discoverPackages(): Promise<{
     packages: ScannedPackage[];
     configured: boolean;
-    project: 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 function describeInstalled(project: Project | undefined, scanned: ScannedPackage[]): Promise<InstalledPackage[]>;
-/**
- * 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: Project | undefined): boolean;
-/**
- * Package names the project's package.json declares in any dependency field.
- * @param {Project | undefined} project
- * @returns {Set<string>}
- */
-export function declaredDependencies(project: Project | undefined): Set<string>;
-/**
- * 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: Project | undefined): (name: string, version?: string) => string;
-/**
- * The per-user cache directory the saved copies live in, never inside a
- * project. Standard platform locations only.
- * @returns {string}
- */
-export function defaultCacheDir(): string;
-/**
- * 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 function callSources(project: Project | undefined, request?: {
-    package?: string;
-    version?: string;
-}, options?: {
-    cacheDir?: string;
-    timeoutMs?: number;
-}): Promise<CatalogResult>;
-/**
- * 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: InstalledPackage & {
-    latest?: string;
-}): import("./discover.type.mjs").DiscoverListEntry;
+export function toEntry(pkg: ScannedPackage): import("./discover.type.mjs").DiscoverListEntry;
 /**
  * Locate a component's doc file within the given packages (case-insensitive).
  * @param {ScannedPackage[]} packages
@@ -104,56 +46,7 @@ export function loadValidatedDoc(result: ComponentResolution, { lang, zh }: {
     lang?: string | null;
     zh?: boolean;
 }): Promise<import("./discover.type.mjs").DiscoverDetailDocResponse["data"]>;
-/** The list and detail entry fields for each item kind, in display order. */
-export const KIND_FIELDS: readonly [readonly ["component", "components"], readonly ["template", "templates"], readonly ["doc", "docs"], readonly ["theme", "themes"], readonly ["codemod", "codemods"], readonly ["agent-doc", "agentDocs"]];
 export type ScannedPackage = import("./_package-scanner.mjs").ScannedPackage;
-export type DiscoverPackage = import("../../authoring/discover/type").DiscoverPackage;
-export type DiscoverSource = import("../../authoring/discover/type").DiscoverSource;
-/**
- * An installed integration with what it adds, per kind. `components` is the
- * scanned component list the discover leaves have always used.
- */
-export type InstalledPackage = ScannedPackage & {
-    templates?: string[];
-    docs?: string[];
-    themes?: string[];
-    codemods?: string[];
-};
-/**
- * What one source did on this run.
- */
-export type SourceState = {
-    /**
-     * the source's own name, or where it came from when it
-     * gave none
-     */
-    name: string;
-    /**
-     * `astryx.config`, or the integration that exports it
-     */
-    from: string;
-    status: "fresh" | "saved" | "failed";
-    generatedAt?: string | undefined;
-    complete?: boolean | undefined;
-    /**
-     * when the saved copy in use was written
-     */
-    savedAt?: string | undefined;
-    /**
-     * why the live call failed
-     */
-    error?: string | undefined;
-};
-/**
- * Everything every source returned, merged. When two sources list the same
- * package, the earlier source's entry is kept.
- */
-export type CatalogResult = {
-    sources: SourceState[];
-    packages: Array<DiscoverPackage & {
-        source: string;
-    }>;
-};
 /**
  * A located component doc within a scanned package — the shape returned by
  * {@link findComponent}, consumed by {@link loadValidatedDoc}.
@@ -163,4 +56,3 @@ export type ComponentResolution = {
     docPath: string;
     componentName: string;
 };
-import { Project } from '../../foundation/config/project.mjs';

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;