@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/search/search.test.mjs

@@ -36,6 +36,7 @@ import {
   tokenizeQuery,
   SEARCH_DOMAINS,
 } from './search.mjs';
+import {linkThisCliAsProjectCli} from '../../test-utils/release-fixtures.mjs';
 
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
 const cwd = REPO;
@@ -470,8 +471,10 @@ describe('search leaf — error paths (pinned)', () => {
 
   it('searches the docs without @astryxdesign/core, and throws for a domain that needs it', async () => {
     const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-no-core-'));
+    // A project whose own CLI answers, with no Core installed.
+    linkThisCliAsProjectCli(empty);
     try {
-      // An open search outside an app covers the docs, as `astryx docs` does.
+      // An open search without Core covers the docs, as `astryx docs` does.
       const open = await search('make an integration', {cwd: empty});
       expect(open.data.results.length).toBeGreaterThan(0);
       expect(new Set(open.data.results.map(r => r.domain))).toEqual(
@@ -616,6 +619,42 @@ describe('search leaf — a theme is found by its names; its description is pros
   );
 });
 
+describe('search leaf — components whose docs live in a family folder', () => {
+  it("indexes a family member from its own entry, not the family's keywords", async () => {
+    // HStack and VStack are documented in Stack's doc, whose keywords
+    // (horizontal, vertical, row, column, ...) describe Stack.
+    const reasons = async (/** @type {string} */ query) =>
+      Object.fromEntries(
+        (await search(query, {cwd, type: 'component'})).data.results.map(r => [
+          r.name,
+          r.reason,
+        ]),
+      );
+    const column = await reasons('column');
+    expect(column.HStack ?? '').not.toMatch(/keyword/);
+    expect(column.VStack ?? '').not.toMatch(/keyword/);
+    expect(column.Stack).toMatch(/keyword/);
+    const vertical = (await search('vertical', {cwd, type: 'component'})).data.results.map(
+      r => r.name,
+    );
+    expect(vertical.indexOf('VStack')).toBeGreaterThanOrEqual(0);
+    if (vertical.includes('HStack')) {
+      expect(vertical.indexOf('VStack')).toBeLessThan(vertical.indexOf('HStack'));
+    }
+  }, SLOW);
+
+  it('ranks VStack, HStack and Heading first for their own names, with their own import', async () => {
+    for (const name of ['VStack', 'HStack', 'Heading']) {
+      const r = await search(name.toLowerCase(), {cwd, type: 'component'});
+      expect(r.data.results[0]).toMatchObject({
+        domain: 'component',
+        name,
+        import: `@astryxdesign/core/${name}`,
+      });
+    }
+  }, SLOW);
+});
+
 describe('search leaf — integration components', () => {
   /**
    * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
@@ -827,3 +866,142 @@ describe('search — usage guidance is indexed, a tier below description', () =>
     expect(hit?.score).toBe(45);
   });
 });
+
+describe('search leaf — compound names, other names, and word forms', () => {
+  it('finds a compound name typed as separate words inside a longer query', async () => {
+    const {data} = await search('table header cell with sort arrow', {cwd});
+    expect(
+      data.results.slice(0, 3).map(r => r.name),
+    ).toContain('TableHeaderCell');
+  }, SLOW);
+
+  it('finds a one-word keyword typed as separate words', async () => {
+    // MetadataList declares `keyvalue`.
+    const {data} = await search('key value pairs', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'component',
+      name: 'MetadataList',
+    });
+  }, SLOW);
+
+  it('finds a hook named by its words without the `use` prefix', async () => {
+    const {data} = await search('persisted table column settings', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'hook',
+      name: 'useTableColumnSettings',
+    });
+  }, SLOW);
+
+  it('reads a camelCase identifier as the words it spells', async () => {
+    const {data} = await search('useTablePaginationState', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'hook',
+      name: 'useTablePagination',
+    });
+  }, SLOW);
+
+  it('keeps each identifier of a multi-word query whole', async () => {
+    const {data} = await search('ChatMessageList ChatComposer', {cwd});
+    expect(data.results.slice(0, 2).map(r => r.name).sort()).toEqual([
+      'ChatComposer',
+      'ChatMessageList',
+    ]);
+  }, SLOW);
+
+  it("finds a component by another library's name for it", async () => {
+    for (const [q, name] of [
+      ['ScrollArea viewport', 'ScrollableArea'],
+      ['toggle group of buttons', 'ToggleButtonGroup'],
+      ['circular progress for uploads', 'Spinner'],
+    ]) {
+      const {data} = await search(q, {cwd});
+      expect(data.results[0], q).toMatchObject({domain: 'component', name});
+    }
+  }, SLOW);
+
+  it('reads a one-identifier other name as typed', async () => {
+    const {data} = await search('AppHeader', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'component',
+      name: 'LayoutHeader',
+    });
+  }, SLOW);
+
+  it('adds no near siblings beside an entry the query names outright', async () => {
+    const {data} = await search('top nav mega menu', {cwd});
+    expect(data.results[0]).toMatchObject({name: 'TopNavMegaMenu'});
+    // Its sub-parts start with its name; read joined they would score in the
+    // whole-name tier right under it.
+    const siblings = data.results.filter(
+      r => r.name !== 'TopNavMegaMenu' && r.name.startsWith('TopNavMegaMenu'),
+    );
+    for (const sibling of siblings) expect(sibling.score).toBeLessThan(190);
+  }, SLOW);
+
+  it('ranks an entry the query names above a match on part of another name', async () => {
+    // `table header` names TableHeader; useTableStickyColumns only holds the
+    // words `sticky columns`.
+    const {data} = await search('table header with sticky columns', {cwd});
+    const names = data.results.map(r => r.name);
+    expect(names.indexOf('TableHeader')).toBeLessThan(
+      names.indexOf('useTableStickyColumns') === -1
+        ? Infinity
+        : names.indexOf('useTableStickyColumns'),
+    );
+  }, SLOW);
+
+  it('keeps an entry a query word names by its whole name at its own rank', async () => {
+    // Two words join into TextInput, and TextArea also matches two words
+    // through its joined keyword; one word is still TextArea's whole name.
+    const {data} = await search('text input and textarea with multi line', {
+      cwd,
+    });
+    expect(data.results[0]).toMatchObject({name: 'TextArea'});
+  }, SLOW);
+
+  it('ranks a match on more of the query above a shorter named entry', async () => {
+    const {data} = await search('dropdown menu radio options', {cwd});
+    expect(data.results[0]).toMatchObject({name: 'DropdownMenuRadioItem'});
+  }, SLOW);
+
+  it('lets a plural start a name through its singular', () => {
+    expect(
+      scoreCandidate('tokens', {domain: 'component', name: 'Tokenizer'}),
+    ).toMatchObject({score: 60});
+  });
+
+  it('finds Icon by a glyph name', async () => {
+    for (const q of ['cog', 'lightning bolt']) {
+      const {data} = await search(q, {cwd});
+      expect(data.results[0], q).toMatchObject({
+        domain: 'component',
+        name: 'Icon',
+      });
+    }
+  }, SLOW);
+
+  it('matches a verb form against its verb', () => {
+    // "spacing" lost the final e of "space".
+    expect(
+      scoreCandidate('spacing', {domain: 'component', name: 'Gap', keywords: ['space']}),
+    ).toMatchObject({score: 88});
+    expect(
+      scoreCandidate('dragging', {domain: 'component', name: 'Gap', keywords: ['drag']}),
+    ).toMatchObject({score: 88});
+  });
+
+  it('lets a plural start a longer word through its singular', () => {
+    expect(
+      scoreCandidate('chips', {domain: 'component', name: 'Chipset'}),
+    ).toMatchObject({score: 60});
+    // A four-letter singular is too short: "stats" does not start "statusbar".
+    expect(
+      scoreCandidate('stats', {domain: 'component', name: 'Statusbar'}),
+    ).toBeNull();
+  });
+
+  it('leaves an identifier joined with _ unmatched when nothing has it', async () => {
+    const {data} = await search('qqzz_no_match_here', {cwd});
+    expect(data.results).toEqual([]);
+  }, SLOW);
+});

package/api/search/search.type.d.mts

@@ -30,7 +30,7 @@ export type SearchResultEntry = {
      */
     description: string;
     /**
-     * - Follow-up command to act on this result (e.g. `astryx component Button`, or `astryx theme add neutral` for a theme).
+     * - Follow-up command to act on this result (e.g. `astryx component Button`, or `astryx theme add neutral` for a theme; `astryx theme eject neutral` outside a project).
      */
     command: string;
     /**
@@ -72,6 +72,19 @@ export type SearchResponse = {
         matchCount: number;
         results: SearchResultEntry[];
     };
+    /**
+     * -
+     * `partial`, when an open search could not get the Core that components,
+     * hooks, and templates are read from (such as outside a project, offline,
+     * before the release's Core was downloaded): the domains it skipped and why.
+     * The results are the docs and themes.
+     */
+    meta?: {
+        partial?: {
+            skipped: SearchDomain[];
+            reason: string;
+        };
+    } | undefined;
 };
 /**
  * Options for `search()`.

package/api/search/search.type.mjs

@@ -20,7 +20,7 @@
  * @property {number} score - Relevance score (higher is better).
  * @property {string} reason - Human-readable reason the candidate matched (e.g. `keyword "button"`).
  * @property {string} description - One-line description, when available.
- * @property {string} command - Follow-up command to act on this result (e.g. `astryx component Button`, or `astryx theme add neutral` for a theme).
+ * @property {string} command - Follow-up command to act on this result (e.g. `astryx component Button`, or `astryx theme add neutral` for a theme; `astryx theme eject neutral` outside a project).
  * @property {string} [import] - Import path — present for component and hook results.
  * @property {string} [title] - Doc title — present for doc results.
  * @property {string} [section] - Section key — present when a doc result is one section of a topic; `command` reads only that section.
@@ -38,6 +38,11 @@
  * @property {string} data.query
  * @property {number} data.matchCount - How many candidates matched the query in total, before `limit` was applied. `results` is the bounded slice of that set, so `matchCount > results.length` means the answer was capped.
  * @property {SearchResultEntry[]} data.results
+ * @property {{partial?: {skipped: SearchDomain[], reason: string}}} [meta] -
+ *   `partial`, when an open search could not get the Core that components,
+ *   hooks, and templates are read from (such as outside a project, offline,
+ *   before the release's Core was downloaded): the domains it skipped and why.
+ *   The results are the docs and themes.
  */
 
 /**

package/api/swizzle/_adapter.mjs

@@ -11,7 +11,7 @@
  * (ERR_CORE_NOT_FOUND) when core can't be located.
  */
 
-import {findCoreDir, listComponents} from '../../foundation/fs/paths.mjs';
+import {findProjectCoreDir, listComponents} from '../../foundation/fs/paths.mjs';
 import {resolveComponentReplacements} from '../../foundation/discovery/component-replacement.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../error.mjs';
@@ -44,7 +44,7 @@ export async function resolveComponentReplacement(
  * @returns {{coreDir: string, components: string[]}}
  */
 export function resolveCore(cwd) {
-  const coreDir = findCoreDir(cwd);
+  const coreDir = findProjectCoreDir(cwd);
   if (!coreDir) {
     throw new AstryxError(
       'Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed.',

package/api/swizzle/copy/copy.mjs

@@ -21,8 +21,10 @@ import {checkGhCli} from '../_github.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {
   CORE_PACKAGE,
-  findIntegrationComponentDoc,
-  findIntegrationComponentSource,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  unscopedComponentOwners,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError, writeFailed} from '../../error.mjs';
@@ -113,7 +115,7 @@ function buildFeedback(component, issuesUrl) {
  */
 async function loadConfigSafely(cwd) {
   try {
-    const project = await Project.load(cwd);
+    const project = await Project.load(cwd, {core: 'project'});
     return {
       loadedIntegrations: project.loadedIntegrations,
       issuesUrl: project.config.issuesUrl,
@@ -126,33 +128,38 @@ async function loadConfigSafely(cwd) {
 
 /**
  * Build the set of OWNER packages that provide a component named `name` across
- * core + every loaded integration.
+ * core + every loaded integration. Core holds every name it documents, but has
+ * source to copy (`sourceDir`) only for a name with its own folder.
  * @param {string} coreDir
  * @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
  * @param {string} name
  * @param {string|undefined} coreIssuesUrl
- * @returns {Array<{package: string, sourceDir: string|null, ownerPackage: string, issuesUrl: string|undefined}>}
+ * @returns {Array<{package: string, sourceDir: string|null, docPath: string|null, ownerPackage: string, issuesUrl: string|undefined, hold: string}>}
  */
 function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
   const owners = [];
   const coreComponentDir = path.join(coreDir, 'src', name);
-  if (fs.existsSync(coreComponentDir)) {
+  const coreFolder = fs.existsSync(coreComponentDir);
+  if (coreFolder || findComponentReadme(coreDir, name)) {
     owners.push({
       package: CORE_PACKAGE,
-      sourceDir: coreComponentDir,
+      sourceDir: coreFolder ? coreComponentDir : null,
+      docPath: null,
       ownerPackage: CORE_PACKAGE,
       issuesUrl: coreIssuesUrl || DEFAULT_ISSUES_URL,
+      hold: 'core',
     });
   }
   for (const integration of loadedIntegrations) {
-    const docPath = findIntegrationComponentDoc(integration, name);
-    if (!docPath) continue;
-    const sourcePath = findIntegrationComponentSource(integration, name);
+    const found = findIntegrationComponent(integration, name);
+    if (!found) continue;
     owners.push({
       package: integration.name,
-      sourceDir: sourcePath ? path.dirname(sourcePath) : null,
+      sourceDir: found.sourcePath ? path.dirname(found.sourcePath) : null,
+      docPath: found.docPath,
       ownerPackage: integration.name,
       issuesUrl: integration.issuesUrl,
+      hold: found.hold,
     });
   }
   return owners;
@@ -222,25 +229,32 @@ export async function swizzleCopy(component, options = {}) {
     : undefined;
   // An active integration replacement answers to the Core name it replaces,
   // bare or qualified by its own package (spec:AST-035 FR11): copy it under its
-  // own name. `--package @astryxdesign/core` still copies the Core original.
+  // doc's file name, the folder it has always gone to. `--package
+  // @astryxdesign/core` still copies the Core original.
   if (pkg !== CORE_PACKAGE) {
     const replacement = await resolveComponentReplacement(
       coreDir,
       loadedIntegrations,
       dirName,
     );
+    const copyName = replacement ? docStem(replacement.docPath) : null;
     if (
       replacement &&
-      (!pkg || (pkg === replacement.package && replacement.name !== dirName))
+      copyName &&
+      (!pkg || (pkg === replacement.package && copyName !== dirName))
     ) {
-      return swizzleCopy(replacement.name, {
+      return swizzleCopy(copyName, {
         ...options,
         package: replacement.package,
       });
     }
   }
 
-  const allOwners = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+  const found = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+  // The owner rule, then a Core name without its own folder drops out.
+  const allOwners = (pkg ? found : unscopedComponentOwners(found)).filter(
+    owner => owner.package !== CORE_PACKAGE || owner.sourceDir != null,
+  );
 
   if (allOwners.length === 0) {
     throw new AstryxError(

package/api/template/template-integration.test.mjs

@@ -736,7 +736,7 @@ describe('integration template discovery', () => {
     const command = await runCli(['template', 'shell-side-nav'], tmpDir);
     expect(command.status).toBe(0);
     expect(command.stderr).toContain('@acme/extra has 1 integration issue');
-    expect(command.stderr).toContain('astryx doctor');
+    expect(command.stderr).toMatch(/Run: .+ doctor/);
 
     const doctor = await runCli(['doctor'], tmpDir);
     expect(doctor.status).toBe(0);

package/api/template/template.test.mjs

@@ -1,7 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import {describe, it, expect} from 'vitest';
-import {stripTemplateAssetRefs, template} from './template.mjs';
+import {
+  stripTemplateAssetRefs,
+  template,
+  extractComponents,
+} from './template.mjs';
 
 describe('stripTemplateAssetRefs', () => {
   it('replaces a /template-assets image path with an inline data URI', () => {
@@ -31,8 +38,7 @@ describe('stripTemplateAssetRefs', () => {
   });
 
   it('preserves surrounding source structure', () => {
-    const src =
-      "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
+    const src = "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
     const out = stripTemplateAssetRefs(src);
     expect(out).toContain("alt: 'X'");
     expect(out).toContain('const data = [{src:');
@@ -102,4 +108,115 @@ describe('template --skeleton component extraction (prefix-agnostic)', () => {
 
     expect(result.data.skeleton).toContain('columns={{minWidth: 200}}');
   });
+
+  it('filters out local helper components declared in the same file', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import {Card} from '@astryxdesign/core/Layout';
+
+function TimelineSection() {
+  return <div />;
+}
+
+export default function Page() {
+  return (
+    <Card>
+      <TimelineSection />
+    </Card>
+  );
+}
+      `,
+    );
+
+    try {
+      const components = extractComponents(pagePath);
+      expect(components).toContain('Card');
+      expect(components).not.toContain('Timeline');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('filters out a type-annotated local helper', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import type {FC} from 'react';
+import {Card} from '@astryxdesign/core/Layout';
+
+const TimelineSection: FC = () => <div />;
+
+export default function Page() {
+  return (
+    <Card>
+      <TimelineSection />
+    </Card>
+  );
+}
+`,
+    );
+    try {
+      const components = extractComponents(pagePath);
+      expect(components).toContain('Card');
+      expect(components).not.toContain('Timeline');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('keeps an imported component when declaration-like text appears in a comment or string', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import {Card} from '@astryxdesign/core/Layout';
+
+// const Card = () => null;
+const note = 'function Card() {}';
+
+export default function Page() {
+  return <Card>{note}</Card>;
+}
+`,
+    );
+    try {
+      expect(extractComponents(pagePath)).toContain('Card');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('keeps a bare imported component whose name is itself a stripped suffix', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import {Section} from '@astryxdesign/core/Section';
+
+function SectionHeading() {
+  return <div />;
+}
+
+export default function Page() {
+  return (
+    <Section>
+      <SectionHeading />
+    </Section>
+  );
+}
+`,
+    );
+    try {
+      expect(extractComponents(pagePath)).toContain('Section');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
 });

package/api/theme/_adapter.d.mts

@@ -129,6 +129,22 @@ export function removeThemeFromApp(slug: string, options?: {
 export function useThemeInApp(slug: string, options?: {
     cwd?: string;
 }): Promise<import("./theme.type.mjs").ThemeAppResponse>;
+/**
+ * The Core theme targets are read 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 requireThemeCoreDir(cwd: string): string;
+/**
+ * The Core a theme build reads outside a project: the one the answering copy
+ * carries, installed into the per-user cache first when needed (a network
+ * install and an npm subprocess; spec AST-081 FR3); null when there is none.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function fetchCarriedThemeCoreDir(cwd: string): string | null;
 /**
  * A bundled theme entry kept for the historical public `listThemes()` helper.
  */

package/api/theme/_adapter.mjs

@@ -11,6 +11,10 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {
+  findCarriedCoreDir,
+  requireCoreDir,
+} from '../../foundation/fs/paths.mjs';
 import {Project} from '../../foundation/config/project.mjs';
 import {
   BUNDLED_THEME_PACKAGE,
@@ -41,6 +45,7 @@ import {stripCopyrightHeader} from '../../foundation/text/copyright-header.mjs';
 import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
 import {importThemeArtifact} from '../../foundation/fs/module-loader.mjs';
 import {applyWrites} from '../integration/add-helpers.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 export {BUNDLED_THEME_PACKAGE, THEMES_DIR};
 
@@ -565,7 +570,7 @@ export function resolveRecordedThemes(state, available) {
     );
     if (!theme) {
       throw new AstryxError(
-        `Added theme "${slug}" from ${owner} is unavailable. Reinstall the package or restore the local theme, then run \`astryx theme add ${slug} --package ${owner}\`.`,
+        `Added theme "${slug}" from ${owner} is unavailable. Reinstall the package or restore the local theme, then run \`${formatCliCommand(`theme add ${slug} --package ${owner}`, state.projectDir)}\`.`,
         undefined,
         ERROR_CODES.ERR_UNKNOWN_THEME,
       );
@@ -732,14 +737,14 @@ export async function removeThemeFromApp(slug, options = {}) {
   const recordedSlug = recordedThemeSlug(state, slug);
   if (!state.configured || recordedSlug == null) {
     throw new AstryxError(
-      `Theme "${slug}" is not added. Run \`astryx theme add ${slug}\` first.`,
+      `Theme "${slug}" is not added. Run \`${formatCliCommand(`theme add ${slug}`, state.projectDir)}\` first.`,
       undefined,
       ERROR_CODES.ERR_UNKNOWN_THEME,
     );
   }
   if (state.defaultSlug === recordedSlug) {
     throw new AstryxError(
-      `Theme "${recordedSlug}" is the default. Run \`astryx theme use <other-slug>\` before removing it.`,
+      `Theme "${recordedSlug}" is the default. Run \`${formatCliCommand('theme use <other-slug>', state.projectDir)}\` before removing it.`,
       undefined,
       ERROR_CODES.ERR_THEME_INVALID,
     );
@@ -748,7 +753,7 @@ export async function removeThemeFromApp(slug, options = {}) {
   delete themes[recordedSlug];
   if (state.defaultSlug == null) {
     throw new AstryxError(
-      'The generated theme module has no default theme. Run `astryx theme use <slug>` first.',
+      `The generated theme module has no default theme. Run \`${formatCliCommand('theme use <slug>', state.projectDir)}\` first.`,
       undefined,
       ERROR_CODES.ERR_THEME_INVALID,
     );
@@ -776,7 +781,7 @@ export async function useThemeInApp(slug, options = {}) {
   const recordedSlug = recordedThemeSlug(state, slug);
   if (!state.configured || recordedSlug == null) {
     throw new AstryxError(
-      `Theme "${slug}" is not added. Run \`astryx theme add ${slug}\` first.`,
+      `Theme "${slug}" is not added. Run \`${formatCliCommand(`theme add ${slug}`, state.projectDir)}\` first.`,
       undefined,
       ERROR_CODES.ERR_UNKNOWN_THEME,
     );
@@ -792,3 +797,25 @@ export async function useThemeInApp(slug, options = {}) {
     available,
   );
 }
+
+/**
+ * The Core theme targets are read 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 requireThemeCoreDir(cwd) {
+  return requireCoreDir(cwd);
+}
+
+/**
+ * The Core a theme build reads outside a project: the one the answering copy
+ * carries, installed into the per-user cache first when needed (a network
+ * install and an npm subprocess; spec AST-081 FR3); null when there is none.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function fetchCarriedThemeCoreDir(cwd) {
+  return findCarriedCoreDir(cwd, {fetch: true});
+}

package/api/theme/build/build.d.mts

@@ -110,13 +110,14 @@ export function themeBuildForReport(file: string, options?: {
     receipt: import("../theme.type.mjs").ThemeBuildResponse | import("../theme.type.mjs").ThemeBuildCheckResponse | null;
     trailer: ThemeBuildTrailer | null;
 }>;
-/** @param {string} file @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options] @param {{cwd?: string}} [ctx] @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>} */
+/** @param {string} file @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options] @param {{cwd?: string, projectCore?: boolean}} [ctx] `projectCore`: read only the project's installed Core, never the carried one (doctor; spec AST-081 FR3) @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>} */
 export function themeBuild(file: string, options?: {
     out?: string;
     check?: boolean;
     iconsSpecifier?: string;
 }, ctx?: {
     cwd?: string;
+    projectCore?: boolean;
 }): Promise<import("../theme.type.mjs").ThemeBuildResponse | import("../theme.type.mjs").ThemeBuildCheckResponse | null>;
 /** @param {string[]} files @param {{familyKey: string, check?: boolean, iconsSpecifier?: string, __onPrivateVarError?: () => void}} options @param {{cwd?: string}} [ctx] */
 export function themeBuildFamily(files: string[], options: {