@astryxdesign/cli 0.7.2-canary.fdd384f → 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(
@@ -863,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

@@ -115,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,

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/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: {

package/api/theme/build/build.mjs

@@ -70,7 +70,11 @@ import {
   CLI_ROOT,
   findCoreDir,
   findInstalledPackage,
+  findProjectCoreDir,
 } from '../../../foundation/fs/paths.mjs';
+import {isGlobalCopy} from '../../../foundation/release/choose.mjs';
+import {isInReleaseCache} from '../../../foundation/release/cache.mjs';
+import {fetchCarriedThemeCoreDir} from '../_adapter.mjs';
 import {
   assertWithin,
   sanitizeName,
@@ -306,10 +310,15 @@ function realLocation(target) {
  *
  * @param {string} cwd
  * @param {CoreBindings} cliCore - The CLI's own Core, from {@link loadCliCore}.
+ * @param {{projectOnly?: boolean}} [options] `projectOnly`: never the
+ *   carried Core, as for doctor (spec AST-081 FR3)
  * @returns {Promise<CoreBindings | null>}
  */
-async function loadProjectCore(cwd, cliCore) {
-  const dir = findInstalledPackage(cwd, '@astryxdesign/core');
+async function loadProjectCore(cwd, cliCore, {projectOnly = false} = {}) {
+  // Outside a project, the Core the answering copy carries (spec AST-081 FR3).
+  const dir =
+    findInstalledPackage(cwd, '@astryxdesign/core') ??
+    (projectOnly ? null : fetchCarriedThemeCoreDir(cwd));
   const themeFile = dir ? importTarget(dir, './theme') : null;
   if (!dir || !themeFile) return null;
   if (cliCore.themeModule) {
@@ -355,14 +364,54 @@ const _projectCores = new Map();
 
 /**
  * Choose the Core this build generates with: the project's installed one when
- * {@link loadProjectCore} finds it, else the CLI's own.
+ * {@link loadProjectCore} finds it, else the CLI's own. With `projectOnly`,
+ * only the project's installed Core: a build that cannot use it fails rather
+ * than read the Core the answering copy carries (spec AST-081 FR3).
  * @param {string} cwd
+ * @param {{projectOnly?: boolean}} [options]
  */
-async function selectCore(cwd) {
+async function selectCore(cwd, {projectOnly = false} = {}) {
   const cliCore = await loadCliCore();
-  if (!_projectCores.has(cwd))
-    _projectCores.set(cwd, await loadProjectCore(cwd, cliCore));
-  setCore(_projectCores.get(cwd) ?? cliCore);
+  const key = `${projectOnly ? 'project' : 'any'}\0${cwd}`;
+  if (!_projectCores.has(key))
+    _projectCores.set(key, await loadProjectCore(cwd, cliCore, {projectOnly}));
+  const projectCore = _projectCores.get(key);
+  // A global or cached copy's own Core is the carried one.
+  if (projectOnly && !projectCore && carriesCore() && !cliCoreIsProjects(cwd)) {
+    throw new AstryxError(
+      "The project's Core isn't installed or does not load.",
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
+  setCore(projectCore ?? cliCore);
+}
+
+/**
+ * Whether this CLI copy is one installed for the computer or kept in the
+ * per-user release cache, whose own Core import is the carried Core.
+ * @returns {boolean}
+ */
+function carriesCore() {
+  return isGlobalCopy(CLI_ROOT) || isInReleaseCache(CLI_ROOT);
+}
+
+/**
+ * Whether the Core the CLI's own import loads is the one the project at
+ * `cwd` installed.
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function cliCoreIsProjects(cwd) {
+  const dir = findProjectCoreDir(cwd);
+  if (!dir) return false;
+  try {
+    const own = fileURLToPath(import.meta.resolve('@astryxdesign/core/theme'));
+    const theirs = importTarget(dir, './theme');
+    return theirs != null && realOrSelf(own) === realOrSelf(theirs);
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -401,8 +450,7 @@ function inAstryxRepository(cwd) {
  * @returns {string}
  */
 export function coreUnavailableMessage(cwd, importError) {
-  const why =
-    '`astryx theme build` generates CSS with @astryxdesign/core, the same code the runtime <Theme> uses';
+  const why = `\`${formatCliCommand('theme build')}\` generates CSS with @astryxdesign/core, the same code the runtime <Theme> uses`;
   const detail = importError ? `\n  Import error: ${importError.message}` : '';
   if (inAstryxRepository(cwd)) {
     return (
@@ -2497,13 +2545,14 @@ function validateHeadingTypeAugmentationSupport(themeDef) {
  *   output must stay inside, for a CLI-internal scratch build. `iconsSpecifier` overrides the icon registry import
  *   specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
  *   direct registry specifiers from the theme source are emitted unchanged.
- * @param {{cwd?: string}} [ctx]
+ * @param {{cwd?: string, projectCore?: boolean}} [ctx] `projectCore`: only the
+ *   project's installed Core (spec AST-081 FR3)
  * @returns {Promise<any>}
  */
 async function themeBuildInternal(
   file,
   options = {},
-  {cwd = process.cwd()} = {},
+  {cwd = process.cwd(), projectCore = false} = {},
   /** @type {{compact?: boolean, trailers?: ThemeBuildTrailer[]}} */ report = {},
 ) {
   const filePath = path.resolve(cwd, file);
@@ -2522,7 +2571,14 @@ async function themeBuildInternal(
   // A compact report has no per-theme heading, so each warning names its file.
   const source = report.compact ? `${path.relative(cwd, filePath)}: ` : '';
 
-  await selectCore(cwd);
+  if (projectCore && !findProjectCoreDir(cwd)) {
+    throw new AstryxError(
+      "The project's Core isn't installed.",
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
+  await selectCore(cwd, {projectOnly: projectCore});
 
   // Standalone builds only need interception when an older Core could erase
   // adaptations. Family preparation always supplies the same recorder as its
@@ -3272,7 +3328,7 @@ export function printCompactTrailer(trailers, {hint = false} = {}) {
       )
       .join(', ');
     logger.log(
-      `[note] Fonts named but not loaded: ${named}. Load them in your app (recipe: astryx docs typography).`,
+      `[note] Fonts named but not loaded: ${named}. Load them in your app (recipe: ${formatCliCommand('docs typography')}).`,
     );
   }
   if (hint) {
@@ -3327,7 +3383,7 @@ export async function themeBuildForReport(
   return {receipt, trailer: trailers[0] ?? 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 async function themeBuild(file, options = {}, ctx = {}) {
   return /** @type {any} */ (themeBuildInternal(file, options, ctx));
 }

package/api/theme/build/build.packed-old-core.test.mjs

@@ -37,6 +37,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 
 import {findInstalledPackage} from '../../../foundation/fs/paths.mjs';
+import {CLI_VERSION} from '../../../test-utils/release-fixtures.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(HERE, '../../../../..');
@@ -55,8 +56,12 @@ const RUNTIME_DEPS = [
   'zod',
 ];
 
-const OLD_CORE_VERSION = '0.5.4';
-const CURRENT_CORE_VERSION = '0.6.0';
+// Both Cores carry the packed CLI's own version: a run through the bin in a
+// project whose Core is another release is handed to that release (spec
+// AST-081 FR2), so the old surface is told apart by what it exports, not by
+// its version.
+const OLD_CORE_VERSION = CLI_VERSION;
+const CURRENT_CORE_VERSION = CLI_VERSION;
 const TSC_BIN = path.join(REPO_ROOT, 'node_modules/typescript/bin/tsc');
 
 /**
@@ -278,8 +283,20 @@ function buildTheme(themeFile, extraArgs = []) {
     'node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs',
   );
   try {
+    // A packed CLI outside any project's package.json reads as installed for
+    // the computer, so it gets a home folder of its own: nothing it keeps for
+    // the computer lands in the real one.
+    const home = path.join(root, 'home');
+    const env = {
+      ...process.env,
+      HOME: home,
+      USERPROFILE: home,
+      XDG_CONFIG_HOME: path.join(home, '.config'),
+      XDG_CACHE_HOME: path.join(home, '.cache'),
+      NO_UPDATE_NOTIFIER: '1',
+    };
     // prettier-ignore
-    const stdout = execFileSync(process.execPath, [bin, 'theme', 'build', ...(Array.isArray(themeFile) ? themeFile : [themeFile]), ...extraArgs, '--json'], {cwd: consumer, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']});
+    const stdout = execFileSync(process.execPath, [bin, 'theme', 'build', ...(Array.isArray(themeFile) ? themeFile : [themeFile]), ...extraArgs, '--json'], {cwd: consumer, encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe']});
     return {status: 0, envelope: JSON.parse(stdout)};
   } catch (error) {
     const e = /** @type {any} */ (error);

package/api/theme/build/font-warning.mjs

@@ -21,9 +21,11 @@
  * @output Ordered, case-insensitively deduped family names, and the human
  *   help snippet (<link> pair + @font-face) printed after the install
  *   instructions.
- * @position Sits beside build.mjs (api/theme/build/). Pure functions, no IO,
- *   so the `--json` receipt and the human output share one source of truth.
+ * @position Sits beside build.mjs (api/theme/build/). Pure functions, no IO
+ *   beyond the CLI invocation the human help names (formatCliCommand), so the
+ *   `--json` receipt and the human output share one source of truth.
  */
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 
 // font-family values that never need loading: CSS generic families, the ui-*
 // system keywords, and CSS-wide keywords that can appear in a token value.
@@ -254,6 +256,6 @@ function fontLoadingRecipe(families) {
       font-display: swap;
     }
 
-  Recipe and fallback-stack guidance: astryx docs typography
+  Recipe and fallback-stack guidance: ${formatCliCommand('docs typography')}
 `;
 }

package/api/theme/build/font-warning.test.mjs

@@ -15,6 +15,7 @@
 
 import {describe, it, expect} from 'vitest';
 import {collectUnloadedFonts, formatFontLoadingHelp} from './font-warning.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 
 describe('collectUnloadedFonts', () => {
   it('returns webfont families from font-family tokens, skipping known fallbacks', () => {
@@ -255,7 +256,7 @@ describe('formatFontLoadingHelp', () => {
   });
 
   it('points at the docs recipe', () => {
-    expect(help).toContain('astryx docs typography');
+    expect(help).toContain(formatCliCommand('docs typography'));
   });
 
   it('percent-encodes family names in the css2 URL', () => {

package/api/theme/remove/remove.test.mjs

@@ -81,14 +81,14 @@ describe('themeRemove', () => {
   it('refuses to remove the default and names theme use', async () => {
     await expect(themeRemove('ocean', {cwd: tmpDir})).rejects.toMatchObject({
       code: 'ERR_THEME_INVALID',
-      message: expect.stringContaining('astryx theme use'),
+      message: expect.stringContaining(' theme use <other-slug>`'),
     });
   });
 
   it('names theme add when the slug is not added', async () => {
     await expect(themeRemove('missing', {cwd: tmpDir})).rejects.toMatchObject({
       code: 'ERR_UNKNOWN_THEME',
-      message: expect.stringContaining('astryx theme add missing'),
+      message: expect.stringContaining(' theme add missing`'),
     });
   });
 });

package/api/theme/targets/targets.mjs

@@ -12,10 +12,10 @@
  */
 
 import * as path from 'node:path';
-import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {requireThemeCoreDir} from '../_adapter.mjs';
 import {collectThemingTargets} from '../../../foundation/discovery/theming-targets.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {AstryxError} from '../../error.mjs';
+import {AstryxError, coreDirOrThrow} from '../../error.mjs';
 
 /**
  * Whether a target matches the caller's filter loosely: any target whose key,
@@ -46,14 +46,7 @@ function matchesLoosely(target, filter) {
  * @returns {Promise<import('../theme.type.mjs').ThemeTargetsResponse>}
  */
 export async function themeTargets(filter, {cwd = process.cwd()} = {}) {
-  const coreDir = findCoreDir(cwd);
-  if (!coreDir) {
-    throw new AstryxError(
-      'Could not find @astryxdesign/core package',
-      undefined,
-      ERROR_CODES.ERR_CORE_NOT_FOUND,
-    );
-  }
+  const coreDir = coreDirOrThrow(requireThemeCoreDir, cwd);
 
   const all = await collectThemingTargets(path.join(coreDir, 'src'));
   const needle = filter ? String(filter).toLowerCase() : null;