@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/build/_adapter.d.mts

@@ -66,6 +66,14 @@ export function isWeightsFile(file: any): file is import("./kit/weights.mjs").We
  * @returns {string[]} Setup notes (empty when the template needs nothing).
  */
 export function templateSetupNotes(template: PageTemplate, cwd: string): string[];
+/**
+ * The Core a build answers from: the project's, else the release's own,
+ * installed into the per-user cache first when needed (a network install
+ * and an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function requireBuildCoreDir(cwd: string): string;
 export { withListingCache } from "../../foundation/fs/listing-cache.mjs";
 /**
  * A page template the kit can recommend starting from.

package/api/build/_adapter.mjs

@@ -20,7 +20,7 @@ import fs from 'node:fs';
 
 import {discoverTemplates} from '../template/template.mjs';
 import {componentKeywords} from '../search/search.mjs';
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {findCoreDir, requireCoreDir} from '../../foundation/fs/paths.mjs';
 import {analyzeTemplateNeeds} from '../../foundation/discovery/template-needs.mjs';
 
 /**
@@ -177,3 +177,14 @@ export function templateSetupNotes(template, cwd) {
     return [];
   }
 }
+
+/**
+ * The Core a build answers from: the project's, else the release's own,
+ * installed into the per-user cache first when needed (a network install
+ * and an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function requireBuildCoreDir(cwd) {
+  return requireCoreDir(cwd);
+}

package/api/build/build.doc.mjs

@@ -76,6 +76,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: 'a query is given and @astryxdesign/core cannot be found from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'a query is given outside a project, or in a project with nothing installed, and the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
   ],
   examples: [
     {label: 'Get the playbook', code: 'const r = await build();'},

package/api/build/kit/kit.mjs

@@ -28,11 +28,9 @@
  */
 
 import {search, searchedComponents} from '../../search/search.mjs';
-import {findCoreDir} from '../../../foundation/fs/paths.mjs';
-import {AstryxError} from '../../error.mjs';
-import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {coreDirOrThrow} from '../../error.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
-import {loadComponents, loadPageTemplates, loadWeights, templateSetupNotes} from '../_adapter.mjs';
+import {loadComponents, loadPageTemplates, loadWeights, requireBuildCoreDir, templateSetupNotes} from '../_adapter.mjs';
 import {
   asksForNewPage,
   ideaKind,
@@ -260,13 +258,7 @@ export async function buildKit(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 60} = options;
   // A kit is built from Core's components, hooks, and templates. An open
   // search without core covers the docs alone, so the kit asks for core here.
-  if (type !== 'doc' && !findCoreDir(cwd)) {
-    throw new AstryxError(
-      'Could not find @astryxdesign/core package',
-      undefined,
-      ERROR_CODES.ERR_CORE_NOT_FOUND,
-    );
-  }
+  if (type !== 'doc') coreDirOrThrow(requireBuildCoreDir, cwd);
   // search()'s JSDoc @returns widens results to object[]; the SearchResponse
   // shape is the contract (api/search/search.type.mjs). Cast locally rather than
   // tightening the search @returns (a separate follow-up).

package/api/component/_adapter.d.mts

@@ -245,6 +245,37 @@ export function scopeIntegrationMember(docs: LoadedComponentDoc, owner: Ownershi
     parentDoc?: string;
     import?: string;
 };
+/**
+ * A search response with every inline `{@link <target>}` in a component
+ * result's description resolved to the command that opens the doc it names,
+ * as `astryx component` prints it (spec:AST-047 FR9). The response object is
+ * kept, with its results replaced.
+ * @template {{data: {results: any[]}}} R
+ * @param {R} response
+ * @param {string} cwd
+ * @returns {Promise<R>}
+ */
+export function linkSearchResponse<R extends {
+    data: {
+        results: any[];
+    };
+}>(response: R, cwd: string): Promise<R>;
+/**
+ * A component read with every inline `{@link <target>}` in its doc text
+ * resolved to the command that opens the doc it names (spec:AST-047 FR9), in
+ * the detail, its props projection, and each list entry. A Core component's
+ * links resolve against the CLI's own docs; an integration's against that
+ * integration's. A link that names no doc prints as written.
+ * @template {{type: string, package?: string, data?: any}} R
+ * @param {R} response
+ * @param {string} cwd
+ * @returns {Promise<R>}
+ */
+export function linkComponentResponse<R extends {
+    type: string;
+    package?: string;
+    data?: any;
+}>(response: R, cwd: string): Promise<R>;
 /**
  * Internal ambiguity marker. Single-component callers still receive the same
  * AstryxError code, message, and suggestions; batch callers can additionally

package/api/component/_adapter.mjs

@@ -22,7 +22,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {
-  findCoreDir,
+  requireCoreDir as requireAnswerCoreDir,
   discoverExternalPackages,
 } from '../../foundation/fs/paths.mjs';
 import {
@@ -44,7 +44,12 @@ import {Project} from '../../foundation/config/project.mjs';
 import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
 import {resolveComponentReplacements} from '../../foundation/discovery/component-replacement.mjs';
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
-import {AstryxError} from '../error.mjs';
+import {AstryxError, coreDirOrThrow} from '../error.mjs';
+import {
+  componentLinkProvider,
+  linkComponentDoc,
+  loadDocsCatalog,
+} from '../docs/_adapter.mjs';
 
 export {CORE_PACKAGE, unscopedComponentOwners};
 
@@ -116,15 +121,7 @@ export {CORE_PACKAGE, unscopedComponentOwners};
  * @returns {string}
  */
 export function requireCoreDir(cwd) {
-  const coreDir = findCoreDir(cwd);
-  if (!coreDir) {
-    throw new AstryxError(
-      'Could not find @astryxdesign/core package',
-      undefined,
-      ERROR_CODES.ERR_CORE_NOT_FOUND,
-    );
-  }
-  return coreDir;
+  return coreDirOrThrow(requireAnswerCoreDir, cwd);
 }
 
 /**
@@ -669,3 +666,114 @@ export function scopeIntegrationMember(docs, owner, dirName) {
   if (docs.import) scoped.import = docs.import;
   return scoped;
 }
+
+/**
+ * A search response with every inline `{@link <target>}` in a component
+ * result's description resolved to the command that opens the doc it names,
+ * as `astryx component` prints it (spec:AST-047 FR9). The response object is
+ * kept, with its results replaced.
+ * @template {{data: {results: any[]}}} R
+ * @param {R} response
+ * @param {string} cwd
+ * @returns {Promise<R>}
+ */
+export async function linkSearchResponse(response, cwd) {
+  const results = response.data.results;
+  if (
+    !results.some(
+      result =>
+        result?.domain === 'component' &&
+        typeof result.description === 'string' &&
+        result.description.includes('{@link'),
+    )
+  ) {
+    return response;
+  }
+  const linked = [];
+  for (const result of results) {
+    if (
+      result?.domain !== 'component' ||
+      typeof result.description !== 'string' ||
+      !result.description.includes('{@link')
+    ) {
+      linked.push(result);
+      continue;
+    }
+    const read = await linkComponentResponse(
+      {
+        type: 'component.detail',
+        package: result.package,
+        data: {description: result.description},
+      },
+      cwd,
+    );
+    linked.push({...result, description: read.data.description});
+  }
+  response.data = {...response.data, results: linked};
+  return response;
+}
+
+/**
+ * A component read with every inline `{@link <target>}` in its doc text
+ * resolved to the command that opens the doc it names (spec:AST-047 FR9), in
+ * the detail, its props projection, and each list entry. A Core component's
+ * links resolve against the CLI's own docs; an integration's against that
+ * integration's. A link that names no doc prints as written.
+ * @template {{type: string, package?: string, data?: any}} R
+ * @param {R} response
+ * @param {string} cwd
+ * @returns {Promise<R>}
+ */
+export async function linkComponentResponse(response, cwd) {
+  const {type} = response;
+  if (
+    type !== 'component.detail' &&
+    type !== 'component.detail.props' &&
+    type !== 'component.list'
+  ) {
+    return response;
+  }
+  if (!JSON.stringify(response.data ?? null).includes('{@link')) {
+    return response;
+  }
+  const catalog = await loadDocsCatalog(cwd);
+  /** @type {Map<string, string>} */
+  const declared = new Map();
+  for (const integration of await loadIntegrationsSafely(cwd)) {
+    const id = /** @type {any} */ (integration).providerId;
+    if (typeof id === 'string') declared.set(integration.name, id);
+  }
+  /**
+   * @param {any} doc
+   * @param {string | undefined} owner
+   */
+  const link = async (doc, owner) => {
+    if (typeof owner !== 'string') return doc;
+    try {
+      return (
+        await linkComponentDoc(
+          catalog,
+          componentLinkProvider(owner, declared.get(owner)),
+          doc,
+        )
+      ).doc;
+    } catch {
+      // An owner that is not a provider id links nothing; its text reads as
+      // written.
+      return doc;
+    }
+  };
+  if (type !== 'component.list') {
+    return {...response, data: await link(response.data, response.package)};
+  }
+  /** @type {Record<string, any[]>} */
+  const components = {};
+  for (const [group, entries] of Object.entries(
+    response.data.components ?? {},
+  )) {
+    const linked = [];
+    for (const entry of entries) linked.push(await link(entry, entry?.package));
+    components[group] = linked;
+  }
+  return {...response, data: {...response.data, components}};
+}

package/api/component/component.doc.mjs

@@ -24,7 +24,8 @@ export const doc = {
     'showcase, or example blocks. An integration component that replaces a Core ' +
     'component (its doc sets replaces, and its package declares the CLI range that ' +
     'turns replacement on) answers to the Core name in detail, batch, and list ' +
-    "results; use options.package '@astryxdesign/core' for the original.",
+    "results; use options.package '@astryxdesign/core' for the original." +
+    " In global mode: with `cwd` outside a project, components from integrations installed next to this CLI package globally resolve too; inside a project, only the project's own integrations count. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'component(name?: string | string[], options?: ComponentOptions): Promise<ComponentListResponse | ComponentBatchResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
@@ -164,6 +165,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be resolved from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'outside a project, or in a project with nothing installed, the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
       when: 'options.category is not a string or matches no component group',

package/api/component/component.mjs

@@ -32,6 +32,7 @@ import {
   installedComponentPackageVersion,
   resolveComponentReplacement,
   unscopedComponentOwners,
+  linkComponentResponse,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -257,6 +258,23 @@ async function componentBatch(selectors, options, coreDir) {
  * )>}
  */
 export async function component(name, options = {}) {
+  // Every read resolves the links in the doc text it returns (spec:AST-047
+  // FR9); a batch's results are each a read of their own.
+  return /** @type {any} */ (
+    await linkComponentResponse(
+      await componentRead(name, options),
+      options.cwd ?? process.cwd(),
+    )
+  );
+}
+
+/**
+ * {@link component}, with each `{@link}` in its doc text as written.
+ * @param {string|string[]} [name]
+ * @param {Parameters<typeof component>[1]} [options]
+ * @returns {ReturnType<typeof component>}
+ */
+async function componentRead(name, options = {}) {
   const {
     cwd = process.cwd(),
     list = false,
@@ -357,7 +375,7 @@ export async function component(name, options = {}) {
       requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
     }
     if (target.name !== name || target.package !== packageScope) {
-      return component(target.name, {...options, package: target.package});
+      return componentRead(target.name, {...options, package: target.package});
     }
     name = target.name;
   }
@@ -396,7 +414,10 @@ export async function component(name, options = {}) {
         dirName,
       );
       if (replacement?.package === packageScope) {
-        return component(replacement.name, {...options, package: packageScope});
+        return componentRead(replacement.name, {
+          ...options,
+          package: packageScope,
+        });
       }
     }
     const scoped = classifyScope(packageScope, {
@@ -424,8 +445,17 @@ export async function component(name, options = {}) {
       // a showcase, so skip discovery entirely.
       if (showcase) {
         return scoped.kind === 'core'
-          ? componentDetailShowcase(dirName, {cwd, name, ownerPackage: owner.package})
-          : componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
+          ? componentDetailShowcase(dirName, {
+              cwd,
+              name,
+              ownerPackage: owner.package,
+            })
+          : componentDetailShowcase(dirName, {
+              cwd,
+              name,
+              resolve: false,
+              ownerPackage: owner.package,
+            });
       }
       if (blocks) {
         return componentDetailBlocks(dirName, cwd, owner.package);
@@ -443,7 +473,12 @@ export async function component(name, options = {}) {
 
     // Legacy `pkg.astryx.docs` external package.
     if (showcase) {
-      return componentDetailShowcase(dirName, {cwd, name, packageScope, ownerPackage: packageScope});
+      return componentDetailShowcase(dirName, {
+        cwd,
+        name,
+        packageScope,
+        ownerPackage: packageScope,
+      });
     }
     const extDocPath = resolveLegacyExternalDoc(scoped.ext, dirName);
     if (extDocPath) {
@@ -484,7 +519,7 @@ export async function component(name, options = {}) {
     dirName,
   );
   if (replacement) {
-    return component(replacement.name, {
+    return componentRead(replacement.name, {
       ...options,
       package: replacement.package,
     });
@@ -526,11 +561,19 @@ export async function component(name, options = {}) {
   ) {
     const owner = effectiveOwners[0];
     if (source) {
-      return componentDetailSource(dirName, owner.sourcePath, {name, ownerPackage: owner.package});
+      return componentDetailSource(dirName, owner.sourcePath, {
+        name,
+        ownerPackage: owner.package,
+      });
     }
     if (showcase) {
       // Integration components don't carry showcases — fail without scanning.
-      return componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
+      return componentDetailShowcase(dirName, {
+        cwd,
+        name,
+        resolve: false,
+        ownerPackage: owner.package,
+      });
     }
     const loaded = await loadComponentDoc(owner.docPath, docOpts);
     const docs = scopeIntegrationMember(loaded, owner, dirName);
@@ -548,7 +591,11 @@ export async function component(name, options = {}) {
     );
   }
   if (showcase) {
-    return componentDetailShowcase(dirName, {cwd, name, ownerPackage: CORE_PACKAGE});
+    return componentDetailShowcase(dirName, {
+      cwd,
+      name,
+      ownerPackage: CORE_PACKAGE,
+    });
   }
 
   const resolved = await resolveUnscopedDoc(dirName, {coreDir, cwd, name});
@@ -565,7 +612,10 @@ export async function component(name, options = {}) {
   const sub = scopeSubComponent(docs, dirName, coreDir);
   if (sub) {
     if (props)
-      return componentDetailProps({props: sub.matchingComponent.props}, resolved.resolvedOwnerPackage);
+      return componentDetailProps(
+        {props: sub.matchingComponent.props},
+        resolved.resolvedOwnerPackage,
+      );
     return componentDetail(
       sub.scoped,
       {